Asynchronous Requests

Some API requests cannot be answered instantly, because their processing (such as products images upload) or results generation (such as full snapshot of all products) takes longer time. This type of API requests is processed in two steps:

1. Request is validated, accepted and enqueued.
2. After the job is processed, a webhook is sent and the result can be retrieved.

Each endpoint is either synchronous or asynchronous per definition, not decided at runtime.

Calling an asynchronous request

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

{
   "data": {
      "images": [
         {
            "priority": 1,
            "name": "100.jpg",
            "description": "Špičkový design",
            "downloadUrl": "https://imagesstore.mydomain.cz/images/100.jpg",
         }
      ]
   }
}

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

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

Results retrieval

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

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

ItemeventInstance is the job id assigned when the job was submitted (see above).

At first, you should check the result of the job processing by calling endpoint Job detail /api/system/jobs/{jobId}. Response like shown below is returned.

{
   "data": {
      "jobId": "3ax1844",
      "endpoint": "/api/products/images",
      "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 successful (completed), you will be interested in field resultUrl, which contains URL, where you can directly retrieve the result. In case the job processing had failed, you should be able to get more information in the log field (it contains unstructured text with processing and error information).

The results are stored for 24 hours (see field validUntil), afterwards the link expires. Job information and log files are stored for 30 days.

List of possible statuses:

• completed – successfully completed jobs;
• pending – waiting in the queue;
• running – a job now being processed;
• failed – the job has failed during its processing;
• expired – the result was completed, but the result are already expired;
• killed – the result processing was terminated unexpectedly.

There is also a summary endpoint Jobs list GET /api/system/jobs/ available to provide a complete list of all jobs – queued, running and completed (history of 30 days is kept) jobs are included.