How to handle long-running operations in APIs

· Category: API & REST

Short answer

Long-running operations require asynchronous patterns so clients are not blocked while the server completes processing.

Steps

  1. Accept the request and return 202 Accepted with a status endpoint URI.
  2. Create a resource representing the operation state and expose it via GET.
  3. Update the status resource as the operation progresses through pending, running, completed, or failed.
  4. Optionally support webhook callbacks to notify clients upon completion.
  5. Allow cancellation through DELETE on the status resource when feasible.

Tips

  • Include progress percentages or estimated completion times when possible.
  • Set reasonable polling intervals and communicate them to clients.
  • Expire completed status resources after a retention period to manage storage.
  • Secure status endpoints so clients can only access their own operations.

Common issues

  • Clients polling too frequently and overwhelming the server.
  • Status endpoints returning stale data due to caching.
  • Race conditions where the webhook arrives before the status update is visible.
  • Lack of idempotency causing duplicate long-running jobs on retry.

Example

curl -X GET https://api.example.com/users   -H "Accept: application/json"   -H "Authorization: Bearer $TOKEN"

This curl command demonstrates a standard GET request with headers for content negotiation and bearer token authentication.