Asynchronous Requests

Some API requests cannot be answered instantly because their processing (such as uploading products images) or result generation (such as creating a full snapshot of all products) takes a longer time. These types of API requests are processed in two steps:

1. The request is validated, accepted, and enqueued.
2. Once the job is processed, a webhook is sent, and the result can be retrieved.

Each endpoint is either synchronous or asynchronous by definition, not determined at runtime.

Calling an asynchronous request

The request is sent as usual. For example, a POST /api/products/{guid}/images/shop request with a payload in the body:

{
   "data": {
      "images": [
         {
            "sourceUrl": "https://www.your-eshop.com/cokolada.jpg",
            "priority": 100,
            "description": "Dobrá čokoláda"
         }
      ]
   }
}

If the request is valid, a job is created and a response like the following is returned:

{
   "data": {
      "jobId": "3ax1844"
   }
}

Retrieving Results

Queues are continuously processed on the backend based on available hardware resources and the number of jobs in the queue. Once a job is completed, a webhook is sent:

{
    "eshopId": 222651,
    "event": "job:finished",
    "eventCreated": "2019-01-08T15:13:39+0100",
    "eventInstance": "3ax1844"
}

The eventInstance is the job ID assigned when the job was submitted (see above).

You should first check the result of the job by calling the Job Detail endpoint Job detail /api/system/jobs/{jobId}. The response might look like this:

{
   "data": {
      "jobId": "3ax1844",
      "endpoint": "/api/products/bffa3b98-d968-11e0-b04f-57a43310b768/images/shop",
      "creationTime": "2019-01-09T15:13:39+0100",
      "completionTime": "2019-01-09T15:15:13+0100",
      "duration": "20.123",  
      "status": "completed",
      "resultUrl": "https://eshop.domain.com/api-results/3ax1844-lrmsrf0.json",
      "validUntil": "2019-01-09T15:13:39+0100",
      "log": "possibly a very long text"
   }
}

The most important field is status. If the job completed successfully (completed), the resultUrl field will contain a direct URL to retrieve the result. If the job failed, you can find more information in the log field, which contains unstructured processing and error information.

The result is stored for 24 hours (validUntil). After that, the link expires. Job metadata and logs are stored for 30 days.

List of possible statuses:

• completed – the job was successfully completed.
• pending – the job is waiting in the queue.
• running – the job is currently being processed.
• failed – the job failed during processing.
• expired – the result was completed, but has since expired.
• killed – the job was unexpectedly terminated.

There is also a summary endpoint Jobs list GET /api/system/jobs/, which provides a complete list of all jobs completed, running and completed (a 30-day history is retained).