Retrieving the response to the original request

There are multiple ways to retrieve the response to the initial request.

Response information in the /requests response

The response to the initial call includes a GW-Async-Location header. This header uses the following syntax:

/async/v1/requests/<asyncRequestId>

You can execute a GET on this endpoint to retrieve information about the original request.

The response status

The response includes a status field, which has one of the following values:

  • Accepted - The request is still waiting to be processed.
  • In Progress - The request is being processed, but processing is not yet complete.
  • Complete - The request has been processed.

The response also includes a responseBodyJson attribute. If the original request has been processed and if the original request's response type is application/json, then the responseBodyJson attribute contains the response payload for the initial request.

Response information using the /response endpoint

There is also a /requests/{asyncRequestId}/response endpoint. Calls to this endpoint use the following syntax:

/async/v1/requests/<asyncRequestId>/response

If the original request is complete, this endpoint returns the response to the original request 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 /requests response.
  • The caller application wants to 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.

Note that there are two situations in which this endpoint could return a 400 error:

  • The original request does not yet have a status of Complete. Its status is either still Accepted or In Progress.
  • The original request has a status of Complete, and the response to the original request is a 400 error.

Tutorial: Retrieve information about an asynchronous request

This tutorial assumes you have submitted an asynchronous request to create a user and you have the GW-Async-Location value from the response. For more information, see Tutorial: Send a request asynchronously.

In this tutorial, you will retrieve information about the asynchronous request using both the /requests and /response endpoints.

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. GET http://localhost:8180/pc/rest/<Async-Location>, where <Async-Location> is the value of the GW-Async-Location response header from the initial asynchronous request.
  3. Ensure that, for this request, you do not have Prefer/respond-async header specified in your request. (Although you can submit the /requests call asynchronously, you typically would not want to.)
  4. Click Send.
  5. Send a second request that uses the /response endpoint to retrieve only the response.
    1. Right-click the current tab and choose Duplicate Tab.
    2. In the new tab, add "/response" to the end of the existing URL.
  6. Click Send.

Results

On the first tab, the response object contains information about the response to the original request. Typically, user creation occurs very rapidly, and the original request should already be processed. If so:

  • The completionTime is specified.
  • The responseBodyJson attribute contains the response to the original request. In this case, it is information about the newly created user.
  • The responseStatus is 201.
  • The status has a code of Complete.

On the second tab, the response object contains the same information that would have been returned if the initial request were submitted synchronously.