Synchronous vs. Asynchronous Writes

Synchronous API calls are blocking calls that do not return until either the change has been completed or there has been an error. For asynchronous calls, the response to the API call is returned immediately with a polling URL while the request continues to be processed. In heavier load conditions, it can be more efficient to submit multiple async calls and periodically check the status than to wait for each call to complete before submitting the next one.

The following examples describe how to use the asynchronous feature to create a call type.

Performing Asynchronous Operations

The create, update, and delete operations can be performed asynchronously by including the query parameter async=true. The request is accepted if the operation is valid and the number of outstanding requests does not exceed the capacity. If the request is accepted, the response includes the following items:

  • The response code is HTTP 202, indicating that the request has been accepted for processing.
  • The location header specifies a URL that can be polled to receive updated information on the progress of the request.
  • The response includes a body. See the next section Asynchronous result parameters.

Asynchronous Result Parameters

  • progress: Indicates the current state of the request. Values include the following states:

    • IN_QUEUE: The request passed validation and capacity checks and was put in the queue.

    • IN_PROGRESS: The request is being processed.

Polling the Asynchronous Request Status

Use the URL from the location header of an asynchronous operation request to get updated status. Responses of this request are:

  • If the request has not completed yet, the response contains the HTTP 202 response code, a location header with polling URL, and a response body.
  • If the request has completed, the response is identical to the responses of synchronous operations, including the following:
    • For a successful create, the response code is HTTP 201 and the location header has the URL of the created item.
    • For a successful update or delete, the response code will be HTTP 200.
    • For an unsuccessful update, a body will provide information about the failure.
  • If the request has been in queue for over 30 seconds, then it is removed and an error indicates that the request timed out.