Skip to main content

Synchronous vs. Asynchronous Uploads

Overview​

To upload SCM data to the Scantrust API, Scantrust supports two methods, Synchronous and Asynchronous, each with its own limitations and benefits. Before chosing which method is most suitable for your use-case, make sure you understand the differences.

Synchronous SCM uploads​

When uploading data Synchronously, the API will process and update all your data within the duration of the HTTP-call. If a lot of data is sent, or a lot of codes are updated, this method can potentially time out, requiring the client to resend the request. For this reason, the synchronous update method is only useful for low data volumes

So:

  • The response to a synchronous call will immediately contain the result of the update and possible errors
  • Data will be processed in between your call to the API and the response you'll get back
  • When updating a lot of data in one call, API responses can be slow
  • The API response will typically timeout after 60 seconds with an HTTP status 504 - Gateway Timeout. and no codes will be updated when this happens

Asynchronous SCM Uploads​

When updating data asychronously, the API will create a background job to update your data and responds immediately with a task_id

  • The response to your call will be immediate and contain a task_id
  • The posted data will be processed by the API in the background
  • The returned task_id can be used to check the job status (pending, running, error, ...)
  • API timeouts will not occur

Choosing between Sync and Async​

Sync updates are the easiest to set up due to the immediate response. No callbacks have to be made. It is however only recommended in cases where the number of updated codes is low (fewer than 1000). A good rule of thumb is that whenever updates are done using the extended_id as a key, the system will be fast enough to handle it in the request itself.

Timeout issues usually occur when a SCM key is used as the key to lookup codes. Each SCM key can be linked to thousands of codes and the system will have to process all this data. If you want to use sync updates with SCM key lookups, it is important to estimate the number of codes that are affected. If these run over 20K for one call, you are likely to run in the timeout danger zone.

When the Async method is required for SCM updates, your integration will have to check back on the task_id to find out the result of the SCM update.

Where to go from here​