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:
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.