Asynchronous requests

The OData specification defines asynchronous requests (opens new window) where the client indicates that it prefers the server to respond asynchronously via the respond-async Prefer header. This is helpful for long-running operations.

Lodata handles this by generating a Laravel job (opens new window) which is then processed by Laravel in the same way it handles any other queued job. For this to work your Laravel installation must have a working job queue.

When the client sends a request in this way, the server dispatches the job and returns to the client a monitoring URL. The client can use this URL to retrieve the job output, or its status if not completed or failed. The client can also provide a callback URL to be notified when the job is complete.

The job runner will execute the OData request in the normal way, but will write the output to a Laravel disk (opens new window) for it to be picked up later. The name of this disk is set in the disk option in config/lodata.php. In a multi-server environment this should be some type of shared storage such as NFS or AWS S3. The storage does not need to be client-facing, when the job output is retrieved it is streamed to the client by the Laravel application.

Sending a request

When dispatching a request with Prefer: respond-async, Lodata will return a 202 Accepted header, and a Location header with a URL that can be used to monitor the progress of the request and retrieve the result.

Monitoring the request

The request can be monitored on the returned URL. If the job is not started or in progress the monitoring URL will return 202 Accepted. If it is complete then it will return the result. The HTTP response code of the monitoring URL will be 200 OK, to check the HTTP response code of the request itself check the asyncresult response header.

WARNING

The result of the request can only be retrieved once. After it is retrieved further requests to the monitoring URL will return 404 Not Found.

Cancelling the request

If the request is pending then it can be cancelled by sending a DELETE request to the monitoring URL:

Using a callback

The client can be notified when the request is complete by providing a callback URL. When the request is complete the service will make a GET request to the provided callback. No payload or query parameters are added, the client must provide a callback URL that contains any tracking information needed to match the original request.

GET http://localhost:8000/odata/People
Prefer: respond-async,callback;url=https://client.example.com/callback