Waiting for a response synchronously

When sending an asynchronous call, a caller application can specify an amount of time it is willing to wait for a response.

  • If the call can be processed within the specified time, Cloud API returns the results as if the call had been executed synchronously.
  • If the call cannot be processed within the specified time, Cloud API returns a "202 Accepted" response and a GW-Async-Location header. As is the case with regular asynchronous calls, the caller application must retrieve the results with a second call

You can specify the wait time in seconds or milliseconds.

Specifying wait time in seconds

To specify a wait time in seconds, specify the asynchronous header as:

  • KEY: Prefer
  • VALUE: respond-async, wait=T

where T is the number of seconds the caller application is willing to wait.

Specifying wait time in milliseconds

To specify a wait time in milliseconds, specify the asynchronous header as:

  • KEY: Prefer
  • VALUE: respond-async, wait-ms=T

where T is the number of milliseconds the caller application is willing to wait.

Specifying a 0 wait time

You can force a call to always execute asynchronously and without any initial validation. To do this, specify wait=0 or wait-ms=0.

Tutorial: Send a request asynchronously with a wait time

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more information, see Tutorial: Set up your Postman environment.

In this tutorial, you will submit two requests asynchronously to create a new user. Both will specify a wait time.

Tutorial steps

  1. In Postman, start a new request by:
    1. Clicking the + to the right of the Launchpad tab
    2. Specifying Basic Auth authorization using user su and password gw.
  2. Enter the following call, but do not click Send yet:
    1. POST http://localhost:8080/cc/rest/admin/v1/users
  3. Specify the request payload.
    1. In the first row of tabs (the one that starts with Params), click Body.
    2. In the row of radio buttons, select raw.
    3. At the end of the row of radio buttons, change the drop-down list value from Text to JSON.
    4. Paste the following into the text field underneath the radio buttons. 
      {
  "data": {
    "attributes": {
      "username": "asyncUserNoWait"
    }
  }
}
  4. Add the asynchronous request to the header.
    1. In the first row of tabs, click Headers.
    2. Scroll to the bottom of the existing key/value list.
    3. In the blank row at the bottom of the key/value list, enter the following:
      1. KEY: Prefer
      2. VALUE: respond-async, wait=1
  5. Create a second tab by duplicating the first tab. To do this, right-click the tab and select Duplicate Tab.
  6. Modify the second tab so that it executes with a wait time.
    1. In the request body, change the username value to asyncUserWithWait.
    2. Change the Prefer header so its wait time is "wait-ms=1" instead of "wait=1":
      1. KEY: Prefer
      2. VALUE: respond-async, wait-ms=1
  7. On both tabs, click Send.

Results

The first tab executes an asynchronous call with a wait time of 1 second. The application is able to complete the call within this time, so the response is provided. (The status is "201 Created" and the response to the original call is provided.)

The second tab executes an asynchronous call with a wait time of 1 millisecond. The application is not able to complete the call within this time, so the call is merely accepted. (The status is "202 Accepted" and the response body is blank.)