Chapter 29. Asynchronous Service calls

ServiceBlox allows for asynchronous service calls, so long running transactions can be processed in the background, with no need for an open TCP connection between client and server.

To asynchronously call a service, the client should send it a regular request, adding the lb_async=true parameter to the URL. When receiving an asynchronous request, ServiceBlox will start the background processing, and immediately send a response with HTTP Status 201 (Created), and the polling URL in the Location header.

Note

Depending on the service configuration, asynchronous handling can be the default mode. In this case, the above parameter is not required for asynchronous requests, and lb_async=false should be sent if a synchronous request is desired.

The client should then periodically send GET requests to the polling URL to query the execution status. Invocations to this URL will return HTTP 200 (Ok) if the background processing is still executing, or 303 (See Other) when the execution is complete. In the latter, the Location header will indicate the final response URL. The client should then send a GET request to this URL to get the execution result.

After retrieving the final response, the client should send a HTTP DELETE request to the final response URL. This will free up memory and disk resources.

Alternatively, if the client wants to abort an execution that is still running, a HTTP DELETE request can be sent to the polling URL.

Note

In order to accept asynchronous calls, the service should be configured accordingly. To see more details on how to enable a service to receive asynchronous calls, please check the LogicBlox Administration Guide.

29.1. Asynchronous call return codes

When handling an asynchronous request, different HTTP Status codes can be returned from the server. Below is the list of Status code for each scenario:

Polling
Status Code Description
404 The id in the polling URL was not found in the cache. This indicates that either the id is wrong, or the processing has been removed from the cache.
400 The background execution has been aborted as per client request.
303 The background execution has completed (either successfully or with an error).
200 The asynchronous request is still executing.

Final Response
Status Code Description
404 The background execution is still executing, or, the provided Id was not found in cache. The latter indicates that either the id is wrong, or the processing has been removed from cache.
424 The execution has been aborted as per client request.
Others The status code returned by the target service (note that this could potentially be one of status codes listed above).

Clean up (DELETE on Final response URL)
Status Code Description
410 Indicate there is nothing to delete for the provided id.
200 Resources cleaned up.

Abort
Status Code Description
404 The provided id was not found in cache. This indicates that either the id is wrong, or the processing has been removed from cache.
409 Abort not possible because the execution was already completed.
200 The execution has already been aborted or failed.
202 Execution has been signalized to abort.