Sending a request asynchronously

To send a request asynchronously, include the following header with the request:

  • Key: Prefer
  • Value: respond-async

The caller application can also 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. For more information, see Waiting for a response synchronously.

Validating the call

If no wait time has been specified, Cloud API executes some validation before accepting the call. This includes the following:

  • Verifying the path is valid
  • Verifying the input is well-formed with respect to the schema
  • Verifying the user is authenticated

If any of these validations fail, then the response to the call will be an error.

It is possible for the initial call to get a "202 Accepted" response, even when it has a validation error. This can happen in the following situations:

  • The call has a validation error other than one of the reasons in the previous list. For example, the call could by trying to create a group and the id for the supervisor does not map to any user.
  • The server waits a maximum of 5 seconds for the validation to be completed. If the server is under heavy load and the asynchronous request is queued, or if the validation takes an unusually long time, the server returns a 202 Accepted response without completing the validation.

Response to the call

In most cases, if the call passes initial validation, Cloud API returns the following:

  • A "202 Accepted" response.
  • A response object with an empty body and a set of response headers, including a GW-Async-Location header.

The GW-Async-Location header contains the Async API /requests path that the caller application must use to determine the status of the original call (such as whether the call has been processed) and to access the results. The value for this header uses the following syntax:

/async/v1/requests/<asyncRequestId>

The <asyncRequestId> is a random value that provides secure access to the results of the original call. Because this value provides access to application data, Guidewire recommends keeping it secure.

There are some situations where the response will not be "202 Accepted":

  • If the wait preference is used and the request completes faster than the requested wait time, the response will be synchronous. For information on specifying a wait preference, see Waiting for a response synchronously.
  • If the application is overloaded and unable to process or queue the request, it will return a 503 response.

Tutorial: Send a request asynchronously

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 a request asynchronously to create a new user. (The work needed to create a user is minimal, and one would not normally need to execute this type of request asynchronously. User is used here to simplify the tutorial. User requires no parent entity, has only one required field, and has the same behavior across all InsuranceSuite applications.)

Tutorial steps

  1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
    1. On the Authorization tab, select Basic Auth using user su and password gw.
  2. Enter the following call, but do not click Send yet:
    1. POST http://localhost:8180/pc/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": "asyncUser"
    }
  }
}
  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
  5. Click Send.

Results

The response should be "202 Accepted". To view the value for GW-Async-Location header, click the Headers tab in the response object pane. (This Headers tab is in a row of tabs that starts with Body and Cookies.) This value is used in the next tutorial.