Synchronous vs Asynchronous: Waiting for the Result or Not

Some work finishes before the response; some takes minutes, and the API should say so instead of holding the connection.

A synchronous API call does the work before it responds, so the response carries the result. An asynchronous call accepts the work, responds at once with a way to follow it, and delivers the result later. The choice is forced by time: every proxy, load balancer and client library on the path has a timeout, and work that may outlast it must not be done inside the request.

Picture a reporting endpoint behind a load balancer that closes any request after 60 seconds. The yearly sales report takes 90. Every request fails with a 504, even though the server finishes the report each time and throws it away.

One long report held open, against a quick acceptance and a later result

Synchronousheld for 90 seconds

POST /reports keeps the connection open while the report runs. The load balancer gives up at 60 seconds and returns 504 Gateway Timeout. The client retries, and the server builds the same report again.

Asynchronousaccepted in milliseconds

POST /reports records the job and answers 202 Accepted with a link to it. A worker builds the report in the background. The client fetches the link later and finds the finished report.

What decides it. Work that reliably finishes in a second or two is synchronous; the client waits and gets an answer. Work that may take longer than the shortest timeout on the path, depends on a slow third party, or runs in batches is asynchronous.

What changes for the client. The first response is a promise, not a result. The client needs a way to learn when the work ends and what came of it.

Two ways to deliver the result. The client can poll, asking a status resource until the job ends, or the server can push, sending a webhook to a URL the client registered. Many APIs offer both.

Raising the timeout is not the fix. A longer timeout on one client does nothing for the proxies in between, holds a server connection for the whole job, and still fails when the job runs long on a busy day.

So the API should say from the start which operations are asynchronous, and answer them with an acceptance rather than a held connection.

← → move through sections and cards