Grand Shooting API Documentation (3.0.0)

We respect HTTP standard and REST architecture.

Most of cases you will receive a success response contained in this table:

HTTP code	Description
102	PENDING. The request is threated and takes some time.
200	OK, The request is threated with success.
201	Created, The request is threated with success and a content is created (e.g. for a POST request)
204	No Content, The request is threated with success but return no content in the response.

Please refer to the following table for identify your problem if you receive an HTTP error:

HTTP code	Description
400	Bad request, in the response, you will see which field is missing or invalid.
401	Unauthorized, check if you passed the Authorization Header
404	Not found, the ressource is missing (e.g A user who have been deleted)
405	Method not allowed, the server know the endpoint used but don't permit this method
500	Internal server error, bad news it seems we have a problem

If you have an unidentified response, don't hesitate to contact our support.

Now you are be able to request all of our endpoints.

Rate limiting is on account basis, or more accurately described, per authentication key. There is a limit on the number of simultaneous requests: you can call up to 5 requests per second.

When you exceed this rate limit for any endpoint of our API, the API will return a HTTP 429 “Too Many Requests” response code, and the following error will be returned in the response body:

{ "errors": [ { "message": "Rate limit exceeded" } ] }

If you start coding with our API, you may be interested in having a first global overview of the main concepts behind Grand Shooting.

Note: The platform supports images and videos. This documentation is equally applicable to both and we may use indifferently the two words (images or videos). So, keep in mind that when we describe a feature, it is always applicable to both images and videos.

Productions and Benches

A production is a bunch of images that is processed according to a declared workflow. Every step of the workflow is called a bench.

A classic production is composed of 3 benches:

1. Capture (corresponds to the “LIVE” feature of the web application)
2. Retouching (often called “Phase 1”)
3. Exports (see below) / Validation

You can have 2 retouching benches within the same production. It can be useful for instance if you want a first stage to clean up images with basic operations then a second stage with more in-depth retouching.

Retouching is optional: you can create a production with no retouching bench. On the contrary Capture, Exports and Validation are mandatory.

Be careful: you can update benches and delete retouching benches as long as no files has been loaded. If you delete a bench that contains files, they will be immediately deleted, and you won’t have the possibility to recover them.

To distinguish the benches within a production, the API includes a parameter called benchsetptype wich can take these values:

• 10 – Capture
• 20 – Retouching (phase 1)
• 30 – Retouching (phase 2)
• 40 – Exports / Validation

Exports and Validation

Exports refers to a specific bench of the production: the one before the validation bench.

The way you interact with images inside export and validation benches differs from the interactions within the first benches of the production: you load images to capture and retouching benches, but you just trigger exports to process retouched images. And the processed images are automatically dropped to the validation bench.

So, you never load images either to export benches nor to validation benches.

Be careful: don’t delete retouching benches if they already contain files. Otherwise you would not be able to trigger exports for this production anymore and you would have to start again with a new production.

Templates

Using the web application, you can create new productions from scratch then set up all the parameters by hand: the number of benches, user accesses on every bench, the settings for the export bench, and so on.

It doesn’t really have sense to give this level of precision from our API because the purpose of the API is to automate repetitive workflows.

That’s why you first create templates with predefined settings from the web application. Then, from the API, you instance new productions giving in parameters the Id of the template.

Shooting methods

Photo shoot sessions can be differentiated thanks to shooting methods.

Basically, a shooting method represents a specific way to get pictures of products: it can be products wared on models or it can be still life. You may also use different shooting methods to distinguish photos produced with different machines or technologies.

Therefore, shooting methods give you full control on how you want to monitor the productions: they appear on almost all reports and you will be able to filter for the values they can take.

Note: if you have questions about the best shooting method values for your organization, feel free to ask the support team for advice.

Shooting methods are set up from the web application with admin credentials. From the API, you can list them.

The catalog and its references

It is one of the big features of Grand Shooting: every image or video can be linked to a catalog. Thus, you will be able to organize image production by product references.

There is only one catalog. But you can combine products from different brands within the same catalog. The attributes stored in Grand Shooting are quite classic:

• Up to 3 levels of categories (univers, gamme, family)
• Brand Model
• reference (product_ref)
• Color
• Size
• Description,
• collection,
• gender
• SKU
• EAN

Every item in the catalog is identified in Grand Shooting by another attribute called 'ref' (for product reference). This 'ref' attribute can be a unique id, but it is commonly generated from other attributes.

For example, in the ready to wear market we need to take pictures not only of all product models but also of all color declinations. Then the ref attribute will be constructed from the model reference attribute concatenated with the color attribute.

Example: Model: S18BOHEMIAN
Color: 110
Ref: SS18BOHEMIAN_110

Important: keep in mind that 'ref' values should be unique in the catalog and that they refer to the product that need to be taken in photo.

The 'EAN' attribute is usefull if the samples do have barcodes. In the web application, typing the ref attribute of a product or scanning is barcode is strictly the same. That’s why 'EAN' values should also be unique.

Note: even if the attribute’s name is 'EAN', you don’t have to comply with 'EAN' standard (we don’t check the parity byte)

Note: sometimes you have multiple sizes of the same product references and you don’t know in advance which samples will be shot. Then you don’t know which 'EAN' have to be stored in you catalog. Don’t worry we already faced this issue many times, the support team will help you to find the solution.

Shotlist : list of products to be shot

From Grand Shooting’s web application, the guidelines define per product category how many images are attempted and what are the technical specifications of these images (in terms of size, resolution, ICC profile, …).

Shotlists make an inventory of existing images for every product in your catalog. They explicit the status of the images in your workflow and reveal alerts if an image does not comply with the guidelines.

More generally shotlists can be seen as the cockpit where you can see the work in progress from the point of view of the catalog.

Looks : group of references visible on the same images

This feature is useful especially for the ready to ware market.

Imagine a model wearing clothes: shoes, a pant, a shirt, a coat, … All these clothes make something up called a look.

In this case the looks are mostly composed before starting the photo shoot session. That’s why it makes sense to link images directly to the look and not to product references.

Be careful: the name of the looks have be different of the names of product references in the catalog.

Our first production

So, let’s start with the API. We will stay simple and create a basic production. To do this, simply send the following request:

POST https://api.grand-shooting.com/v3/production

With the body:

    {  
    "smalltext": "My first production",  
    "startdate": "2017-03-27T07:00:00.000Z",
    "enddate": "2017-03-27T16:00:00.000Z",
    "timezone": "Europe/Paris",
    "tzoffset": 60,
    "shooting_method_id": 1,  
    "bench_template_id": 1  
    }

The 2 main parameters are 'shooting_method_id' and 'bench_template_id'. They refer to the shooting method and to the template. They are the only parameters that cannot be changed once the production is created.

We set a smalltext “'My first production'” that will be viewable on the web application as the title of the production.

The 'startdate' parameter gives information about the day the first images shall be uploaded to this production. Usually it is the date of the photo shoot session. The time zone is explicitly set.

'enddate', 'timezone' and 'tzoffset' are optional. In this example the parameters are set to a capture session starting at 7.00 am and ending at 4.00 pm. If omitted, the timezone is set to "Europe/Paris".

List the benches of a production

Now to list all the productions call this request:

GET /production

It will return an array with all the productions, like this one:

    [ 
        [
            {
            "smalltext": "My first production",
            "startdate": "2017-03-27T07:00:00.000Z",
            "enddate": null,
            "timezone": "Europe/Paris",
            "tzoffset": 60,
            "shooting_method_id": 1,
            "bench_id": 1,
            "parent_id": null,
            "root_id": 1,
            "benchsteptype": 10
            },
            {
            "smalltext": "My first production (Retouching)",
            "startdate": "2017-03-27T07:00:00.000Z",
            "enddate": null,
            "timezone": "Europe/Paris",
            "tzoffset": 60,
            "shooting_method_id": 1,
            "bench_id": 2,
            "parent_id": 1,
            "root_id": 1,
            "benchsteptype": 20
            },
            {
            "smalltext": "My first production (Export)",
            "startdate": "2017-03-27T07:00:00.000Z",
            "enddate": null,
            "timezone": "Europe/Paris",
            "tzoffset": 60,
            "shooting_method_id": 1,
            "bench_id": 3,
            "parent_id": 2,
            "root_id": 1,
            "benchsteptype": 40
            }
        ]
    ]

You can see that the previously created production contains 3 benches: Capture ('benchsteptype' = 10), Retouching ('benchsteptype' = 20) and validation ('benchsteptype' = 40).

Benches are chained:

• The first bench of a production has no 'parent_id'.
• The 'root_id' is the id of the first bench for all benches of the production.
• From one bench to the next one you can see that the 'parent_id' changed.

Note : By convention, the 'smalltext' attribute of the first bench of a production is repeated for all benches ("My first production" in this example). Then, the specific name of a bench is set between parenthesis ("Retouching" and "Export" in this example). The first bench of a production can't have any specific name as it is always set as "Live".

If you want to list all productions but not all benches of production, you can filter the benches with null as parent_id.

Load bench of a production

If you need the details about a specific bench, you can call this endpoint:

GET /production/{bench_root_id}/bench/{bench_id}

You will get just the bench:

{
"smalltext": "My first production (Export)",
"startdate": "2017-03-27T07:00:00.000Z",
"enddate": null,
"timezone": "Europe/Paris",
"tzoffset": 60,
"shooting_method_id": 1,
"bench_id": 3,
"parent_id": 2,
"root_id": 1,
"benchsteptype": 40
}

List the pictures of a bench

Once you created a production and you know there are some pictures, you may want to list them. Super easy, just send this request:

GET https://api.grand-shooting.com/v3/picture?bench_id=3

In this example we list images from the third bench. The body of the response is an array of picture objects like this one:

{
"picture_id": 3,
"bench_id": 3,
"bench_root_id": 1,
"ref": "3596654282833",
"path": "4c76bb10-d028-4988-b008-01a97c38a232/3596654282833_3.jpg",
"smalltext": "3596654282833_3.jpg",
"picturestatus": 50,
"filesize": 503637,
"reference_id": 1,
"child_ids": [],
"parent_id": 2
}

File name and path

Basically you can consider that a bench is a secured folder in which files are stored. Files can be organized in subfolders and the path attribute indicates the exact location of a file inside the bench.

So, there might be 2 images with the same filename "3596654282833_3.jpg" in this bench. But there can be just one image with this path ""4c76bb10-d028-4988-b008-01a97c38a232/3596654282833_3.jpg".

Picture status

'picturestatus' attribute refers to the status of an image (or video) inside a production. It can take one of these values :

HTTP code	Description
5	RESHOOT, Image to be shot again.
10	NOT SELECTED, Image in the Live with default status
30	SELECTED, Image in the Live selected for retouching
31	REFUSED, Image refused, need some more work
35	REFUSED, Image refused by the retouchers
40	FOR APPROVAL, Image submitted for approval
50	VALIDATED, Image validated
52	ERROR, Error during the tranfer to the DAM
55	RELEASED, Image transferred to the DAM

Head's up ! : the status of a picture and the type of its bench are correlated. For instance a bench that corresponds to a Live ('benchsteptype' = 10) should only have pictures with status 5, 10 or 30. And a bench that corresponds to a validation step should only have pictures with status above than 40, except for the refused image ('picturestatus' = 31).

Note : Even if an image is not selected (in the Live bench), it can be retouched in the retouching benches then exported for approval. And of course a refused image can be retouched again and exported again for approval.

If Grand Shooting is integrated with a PIM, a DAM or Amazon S3, images will automatically take these status after having been transferred. In most cases, only validated images are transferred.

What is the difference between the 2 REFUSED status ? The common way to refuse an image is in the export bench : the status value of the image is 31. But an image can also be refused by a retoucher in the bench for retouching : in this case the status value is 35.

Upload images

We learned how to list the productions and their benches. Now let's try to upload images.

POST /production/{bench_root_id}/bench/{bench_id}/upload

With a multipart body:

As you can see, it is very simple to integrate our API and manage image productions from your own applications: with few lines of code, you instantiate new productions then load / download images to / from the benches.

Keep in mind that the way you manage images within benches for capture and retouching differs from the interactions you can have with images within benches for export and validation.

Webhook is a pattern that allows external systems to be notified of events occuring in a Sass plaform.

Contribution

You can contribute urls in the administration console that will be notified of picture modifications events. You reference your url to be called for certain types of events :

• picture creation
• picture modification
• picture deletion
• reference creation
• reference modification

Note : you can reference the same url for different types of events.

Process

When a picture is modified in Grand Shooting, the system stores the event in a queue. Every 10 seconds, events are read from the queue and sent to the external url in a "POST" http call with a JSON body containing modified data Example :

    {
      "account_id": 10229487,
      "topic": "pictures/update",
      "type": "picture",
      "ids": [
        175,
        176
      ],
      "picture_id": [ //Deprecated
        175,
        176
      ],
      "data": {
        "175": {
          "picture_id": 175,
          "bench_id": 19,
          "bench_root_id": 19,
          ...
        },
        "176": {
          "picture_id": 176,
          "bench_id": 19,
          "bench_root_id": 19,
          ...
        }
      }
    }

• A message contains at most 50 data elements. (If there are more than 50 data elements modified, a second http call will be processed)
• A message is concidered in success the url returns a http response code of 200
• If a timeout occurs when calling the url or if it returns something else than a code 200, the message is concidered not delivered.
  • The system will retry twice to send the message (after 10 seconds, and after 1 minute)
  • The system won't send any other message to the url for the same topic until it gets a code 200 response or all 3 tries are sent.
• Deprecation : picture_id array field is deprecated and will be removed in next major version. You should use ids field instead