Overview of asynchronous calls

After the call has been submitted, the caller application uses the Async API /requests path from the initial response to retrieve information about the original request. This path takes the form of /async/v1/requests/<asyncRequestId>.

The response to the /requests call always includes the following information:

• The requestMethod and requestPath of the original request
• The status of the original request, which can be set to:
  • Accepted - The request is still waiting to be processed.
  • InProgress - The request is being processed, but processing is not yet complete.
  • Complete - The request has been processed.
• The startTime of the original request

If the original request has been completed, then the following information is also included:

• The completionTime of the original request
• The responseStatus and responseHeaders
• If the response's format is application/json, then the response itself is included in the responseBodyJson field

{
    "data": {
        "attributes": {
            "requestMethod": "POST",
            "requestPath": "/admin/v1/users",
            "responseStatus": 202,
            "startTime": "2022-07-12T16:53:12.365Z",
            "status": {
                "code": "Accepted",
                "name": "Accepted"
            }
        }
    }
}

{
    "data": {
        "attributes": {
            "completionTime": "2022-07-12T16:53:16.073Z",
            "requestMethod": "POST",
            "requestPath": "/admin/v1/users",
            "responseBodyJson": {
                "data": {
                    "attributes": {
                        ...
                        "username": "asyncUser99",
                        "vacationStatus": {
                            "code": "atwork",
                            "name": "At work"
                        }
                    },
                    "checksum": "321dff263827cbbd772c26676398d8ae",
                    "links": {
                    ...
                    }
                }
            },
            "responseHeaders": {
                "Cache-Control": [
                    "must-revalidate",
                    "post-check=0",
                    "pre-check=0",
                    "max-age=0",
                    "no-store",
                    "no-cache"
                ],
                "Content-Type": [
                    "application/json;charset=UTF-8"
                ],
                "GW-Checksum": [
                    "321dff263827cbbd772c26676398d8ae"
                ],
                "Location": [
                    "/admin/v1/users/pc:ScaA3kB5cImBkuh7bxjNn"
                ],
                "X-Correlation-ID": [
                    "d516344d-5769-4964-adb7-79eaca41e4a2"
                ],
                ...
            },
            "responseStatus": 201,
            "startTime": "2022-07-12T16:53:12.365Z",
            "status": {
                "code": "Complete",
                "name": "Complete"
            }
        }
        ...
    }
}

Polling until the original request is complete

The caller application can poll Cloud API periodically until it receives a response whose status is Complete. This is depicted in the following diagram.

1. The caller application sends a GET /async/v1/requests/{asyncRequestId} request to Cloud API. The path comes from the header of the initial response.
2. The Cloud API response includes information about the original request. If the status is Accepted or In Progress, the caller application must re-submit the GET after an appropriate interval.

When the response includes a status of Complete, the caller can retrieve the response to the original request. There are multiple ways that it can be retrieved.

The /requests endpoint returns an AsyncRequest resource. This resource includes a responseBodyJson attribute. If the original request has a status of Complete, and if the response's type is application/json, then this attribute contains the response payload for the initial request.

This is depicted in the following diagram.

4. The caller application sends a GET /async/v1/requests/{asyncRequestId} request to Cloud API. The acyncRequestId comes from the header of the initial response.

5. The Cloud API response includes information about the original request. When the status is Complete, the response includes the original request's response if the response type is application/json.

Note that the GET /async/v1/requests/{asyncRequestId} request could return a response of Complete the first time it is submitted or on a subsequent try.

There is also a /requests/{asyncRequestId}/response endpoint. For completed requests, this endpoint returns the original response as if the call had been executed synchronously. This endpoint is useful when:

• The response type is something other than application/json, and therefore is not included in the GET /async/v1/requests/{asyncRequestId} response.
• The caller application wants the work with the response as it would normally appear, as opposed to having to extract it from within the responseBodyJson attribute of a larger data envelope.

This is depicted in the following diagram.

6. The caller application sends a GET /async/v1/requests/{asyncRequestId}/response request to Cloud API.

7. The Cloud API response includes the original response, as if the request had been executed synchronously.

When the original call is complete, the response to GET /async/v1/requests/{asyncRequestId}/response has the same status code, response body (if any), and response headers as if the caller were getting a synchronous response to the original request.

For example, if the original request was a POST that created a new activity, the GET request to retrieve the response might return a 201 response code and have a Location header. If the original request failed because of a validation error, the GET request to retrieve the response might have a 400 status code and a response body with details of the errors.