HTTP API: Errors, Caching, Concurrency and Long-Running Operations
Objectives
By the end of the lesson, you can explain how a usable HTTP API handles errors, caching, concurrent modification and long-running operations.
Why is it needed?
An API is not designed only for the successful case. The consumer must be able to tell apart bad input, a missing resource, a conflict, overload and a transient dependency failure, and must know what happens if two parties modify at the same time.
Errors: status and details
The status code gives the class of the error: 400 bad request, 401 missing or wrong authentication, 403 forbidden, 404 not found, 409 conflict, 412 precondition failed, 429 too many requests (RFC 6585), 503 temporary overload or maintenance (RFC 9110, with a Retry-After header). 201 means a created resource, 202 accepted but unfinished processing.
For machine-readable details there is the problem details format of RFC 9457 (application/problem+json), whose members are type, title, status, detail and instance. The client should not compare human sentences: a stable error code can be handled programmatically, while the displayed text may change. An error response should not disclose internal stack traces or secret configuration.
Caching and conditional reads
A cache reduces the cost of repeated requests, but the rules of freshness and shareability must be given: a public catalogue needs different handling from a personal list. The ETag identifies the version of a resource representation. The client can use an If-None-Match header to say it already knows a version; if the state is unchanged, the server can answer 304 (a conditional request). This means less data transfer, but it does not make the server-side check free.
Concurrent modification
If two clients have read the same old state, the second modification can overwrite the first. A conditional write (If-Match with the ETag) succeeds only if the client's known version is still current; otherwise the server answers 412. The server must enforce the check and the write together.
sequenceDiagram
participant A as Client A
participant B as Client B
participant S as Service
A->>S: GET
S-->>A: version 7
B->>S: GET
S-->>B: version 7
A->>S: Modify, If-Match 7
S-->>A: Success, version 8
B->>S: Modify, If-Match 7
S-->>B: 412, the version changed
After the conflict the client can re-read the state and decide. Automatic resending with the fresh version can overwrite the other modification without approval.
Long-running operation
A big operation need not be awaited in an open request. 202 Accepted is, according to the RFC, "intentionally noncommittal": the response describes the current status and points to a status monitor. The contract must state the place of the result, the error, the expiry and the possibility of cancellation; the client queries the status (polling, 9.1) or receives a notification (8.5, 9.3).
Pagination
In lists, pagination limits the size of the response. An offset is simple, but in changing data the items can shift. A cursor marks an agreed ordering point; for stable ordering, an ordering key supplemented with an identifier is needed.
Common misconceptions
Statement
Clarification
"200 means every success."
201, 202, 204 are successes with different meanings.
"The ETag is only for caching."
It can also be used for concurrency control (If-Match).
"With pagination an offset is always good."
In changing data it can shift; a cursor is more stable.
"The text of the error message is the contract."
The code is the contract; the text may change.
In short
The status gives the class of the error, problem details the specifics.
ETag and conditional requests give less data transfer and safe writes.
202 marks a long-running operation; the contract gives the status query.
In pagination a cursor is more stable than an offset.
Review questions
What does 412 mean, and when does it appear?
Why is automatic resending dangerous after a conflict?
How would an API express a long-running operation?
HTTP API: Errors, Caching, Concurrency and Long-Running Operations
Objectives
By the end of the lesson, you can explain how a usable HTTP API handles errors, caching, concurrent modification and long-running operations.
Why is it needed?
An API is not designed only for the successful case. The consumer must be able to tell apart bad input, a missing resource, a conflict, overload and a transient dependency failure, and must know what happens if two parties modify at the same time.
Errors: status and details
The status code gives the class of the error:
400bad request,401missing or wrong authentication,403forbidden,404not found,409conflict,412precondition failed,429too many requests (RFC 6585),503temporary overload or maintenance (RFC 9110, with aRetry-Afterheader).201means a created resource,202accepted but unfinished processing.For machine-readable details there is the problem details format of RFC 9457 (
application/problem+json), whose members aretype,title,status,detailandinstance. The client should not compare human sentences: a stable error code can be handled programmatically, while the displayed text may change. An error response should not disclose internal stack traces or secret configuration.Caching and conditional reads
A cache reduces the cost of repeated requests, but the rules of freshness and shareability must be given: a public catalogue needs different handling from a personal list. The
ETagidentifies the version of a resource representation. The client can use anIf-None-Matchheader to say it already knows a version; if the state is unchanged, the server can answer304(a conditional request). This means less data transfer, but it does not make the server-side check free.Concurrent modification
If two clients have read the same old state, the second modification can overwrite the first. A conditional write (
If-Matchwith the ETag) succeeds only if the client's known version is still current; otherwise the server answers412. The server must enforce the check and the write together.After the conflict the client can re-read the state and decide. Automatic resending with the fresh version can overwrite the other modification without approval.
Long-running operation
A big operation need not be awaited in an open request.
202 Acceptedis, according to the RFC, "intentionally noncommittal": the response describes the current status and points to a status monitor. The contract must state the place of the result, the error, the expiry and the possibility of cancellation; the client queries the status (polling, 9.1) or receives a notification (8.5, 9.3).Pagination
In lists, pagination limits the size of the response. An offset is simple, but in changing data the items can shift. A cursor marks an agreed ordering point; for stable ordering, an ordering key supplemented with an identifier is needed.
Common misconceptions
201,202,204are successes with different meanings.If-Match).In short
202marks a long-running operation; the contract gives the status query.Review questions
412mean, and when does it appear?Learning resources
429 Too Many Requests.