Asynchronous endpoints

Some REST API endpoints run asynchronously.

This behavior is helpful if the action that is performed has a long waiting period or has a negative impact on system performance. Some endpoints are explicitly asynchronous, such as the /db2whrest/v1/sql_query_async?<sql>: GET endpoint. Other endpoints are initially synchronous but are automatically converted by the system to asynchronous operations if they take more than 10 seconds to complete.

When you start an endpoint that results in an asynchronous operation, you must poll the asynchronous operation until it is complete. Follow these steps:
  1. Find the location URI of the asynchronous operation. In response to the request that starts the endpoint, the system returns a synchronous response that indicates that asynchronous operation is accepted for processing but is not yet complete. This response includes a status code of 202 ACCEPTED and a response header that contains the location of the asynchronous operation. In the following example, the status code appears at line 2 and the location URI appears in line 5:
    * HTTP 1.0, assume close after body
< HTTP/1.0 202 ACCEPTED
< Content-Type: text/html; charset=utf-8
< Content-Length: 28
< Location: https://labsrv04/db2whrest/v1/task_status/9c0db090-bd33-41c5-969f-a1603ddf49ab
< Server: Werkzeug/0.14.1 Python/3.4.5
< Date: Thu, 15 Feb 2018 20:37:10 GMT
  2. Run the /db2whrest/v1/task_status/<task_id>: GET endpoint on the location URI to get the status of the asynchronous operation. The following example uses the location URI from the example in Step 1:
    curl -k -H 'Authorization: Bearer <token>' https://labsrv04/db2whrest/v1/task_status/9c0db090-bd33-41c5-969f-a1603ddf49ab -X GET
  3. If the status code that is returned from the task_status endpoint in Step 2 is 303, then the asynchronous operation is not completed. Repeat Step 2.
  4. If the status code of the task_status endpoint in Step 2 is 200, then the asynchronous operation completes and the response header contains the location URI of the results. Run the /db2whrest/v1/task_status/<task_id>: GET endpoint on this location URI to get the results.
For more information see the topic /db2whrest/v1/task_status/<task_id>: GET and <task_id>/peek.