# 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
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
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.
The result of the request can only be retrieved once. After it is retrieved further requests to the monitoring URL
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