CS Fundamentals Trainer · Guides
Designing a REST API
Resources and URLs, methods and their guarantees, status codes and errors, and three tested risks: a retried POST that creates two orders, OFFSET paging that repeats items, and conditional requests with ETags.
29 min read
An API is a contract between programs written by different people, often years apart. A good one is predictable: a developer who has used three of its endpoints can guess the fourth, retries are safe, errors say what to do, and next year's changes do not break last year's clients. This guide covers the design decisions that matter most for a REST-style HTTP API and tests the risky ones: the retried POST that creates two orders, OFFSET paging that repeats items, and conditional requests that save bandwidth and stop lost updates.
The experiments were run for this guide against small local servers (Python 3.13 standard library and SQLite), and the database checks in sections 6 and 7 on PostgreSQL 16. Each is a single run on a small machine. Absolute sizes and times depend on your data; the behaviours are what to take away.
1. What "REST" means in practice
REST (Representational State Transfer) is a style described by Roy Fielding in his 2000 dissertation. In everyday use, a "REST API" means:
- Resources are the things the API is about (an order, a customer, a payment). Each has an address (a URL).
- Representations are what you exchange (usually JSON) when you read or change a resource.
- The HTTP method says what you want (read, create, replace, delete) and the status code says what happened. You do not invent your own verbs or put success and failure inside a
200. - Each request carries everything needed to handle it (stateless server), so any server behind a load balancer can answer it. Sessions and caches are then explicit, not hidden.
- Responses say whether they can be cached, and links or ids let clients move around.
Many APIs called REST are really resources plus HTTP verbs without hypermedia links (level 2 of the Richardson maturity model), and that is a perfectly good place to stop. What matters is being consistent.
2. Resources and URLs
- Name resources with nouns, and be consistent about the number. Plural is the common convention:
GET /orders,GET /orders/42,POST /orders. Singular works too; REST does not require either, and what hurts clients is mixing them. The verb is the method, not part of the path (/getOrderand/createOrderare RPC in disguise). - Nest only to show ownership, and only one level deep:
GET /orders/42/items. Beyond that, give the inner thing its own address (/items/7) and filter:GET /items?order=42. - Filter, sort and select with query parameters:
GET /orders?status=paid&sort=-created_at&fields=id,total. - Actions that do not fit CRUD can be a state change or a sub-resource.
PATCH /orders/42with{"status": "cancelled"}suits a plain field update where any value is allowed.POST /orders/42/cancelis a clean design when cancelling is a domain operation with its own rules, side effects (a refund, a notification) and permissions, because it names what happened and gives that rule one place to live. Choose by what the operation means, and keep to one style within a domain. - Ids are opaque, stable strings. Do not expose sequential database ids if guessing the next one is a problem (see persistent identifiers for why a name should outlive its location).
- Keep URLs lower case with hyphens, no file extensions, no trailing slash differences.
3. Methods and their guarantees
Two properties from the HTTP specification decide how a client may use a method:
- A method is safe if it does not change anything on the server. Clients, crawlers and caches may call safe methods freely.
- A method is idempotent if calling it several times has the same effect as calling it once. This is what makes retrying acceptable after a timeout.
| Method | Use | Safe | Idempotent | Typical success |
|---|---|---|---|---|
GET | read a resource or a list | yes | yes | 200 |
HEAD | like GET, headers only | yes | yes | 200 |
POST | create a resource or start an action | no | no | 201 + Location, or 202 |
PUT | replace a resource completely | no | yes | 200 or 204 |
PATCH | change part of a resource | no | not guaranteed | 200 or 204 |
DELETE | remove a resource | no | yes | 204 (or 200) |
Notes that trip people up:
- Idempotent does not mean "same response". The second
DELETE /orders/42can return404; the state of the server is the same. GETmust never change data. A "delete" link that is aGETwill be triggered by prefetchers and crawlers.PATCHis idempotent only if you design it so: "set status to cancelled" is, "add 5 to the balance" is not. Formats exist for describing the change: JSON Merge Patch (RFC 7396) and JSON Patch (RFC 6902).POSTis the dangerous one, because it is neither safe nor idempotent. Section 6 shows what goes wrong and how to fix it.
4. Status codes: say what happened
Choose the most specific code that fits; clients branch on the code before they read the body.
| Code | Meaning | Use it when |
|---|---|---|
200 OK | success with a body | a read or an update that returns the resource |
201 Created | new resource | after POST; add a Location header with its URL |
202 Accepted | work queued, not done | slow operations (section 11) |
204 No Content | success, nothing to return | DELETE, or an update that returns nothing |
301 / 308 | moved permanently | a resource has a new URL |
304 Not Modified | your cached copy is still good | conditional GET (section 9) |
400 Bad Request | the request is malformed | bad JSON, a missing field, a wrong type |
401 Unauthorized | not authenticated | no or invalid credentials; send WWW-Authenticate |
403 Forbidden | authenticated, not allowed | the user may not do this |
404 Not Found | no such resource | also used to hide that a private resource exists |
405 Method Not Allowed | the method is not supported here | send an Allow header |
409 Conflict | clashes with the current state | duplicate unique value, request already running; the client usually has to refresh its view of the state (section 6) |
410 Gone | existed, removed on purpose | retired resources |
412 Precondition Failed | an If-Match condition failed | someone else changed it first (section 9) |
415 Unsupported Media Type | cannot read this Content-Type | JSON expected, got XML |
422 Unprocessable Content | well-formed but invalid | business-rule validation errors |
429 Too Many Requests | rate limited | send Retry-After (see the rate limiter guide) |
500 / 502 / 503 / 504 | server, gateway, overload, timeout | 503 with Retry-After during overload or maintenance |
Two rules matter more than any single code:
- Never return
200with an error inside. Monitoring, caches, retries and client libraries all trust the status line. 4xxmeans the request needs to change,5xxmeans the server failed to complete a valid one. That is a good starting point for reading a response, but it is not a retry policy: some4xxcodes are worth retrying and no5xxtells you whether a write happened. The decision table in section 6 is what a client library should implement.
5. Errors clients can use
Give every error the same shape so clients write one handler. The standard is Problem Details (RFC 9457, media type application/problem+json):
HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
{
"type": "https://api.example.com/problems/validation",
"title": "Your request has invalid fields",
"status": 422,
"detail": "total must be greater than zero",
"instance": "/orders/req-7f3a",
"errors": [{ "field": "total", "message": "must be greater than zero" }]
}
- A stable machine-readable
type(or code) lets clients branch without parsing English. - A human
detailhelps the developer reading the log. - Include a request id (here
instance, or a header) so a user can quote it and you can find the log line. - Never leak internals: no stack traces, SQL or file paths.
- Return
401/403the same way for every endpoint, and avoid telling an attacker whether an account exists (see the guide on authentication).
6. Retries and idempotency keys
A client sends POST /orders. The server creates the order, but the response is slow or lost, and the client times out. The client cannot know whether the order exists. If it retries, it may create a second one.
This was tested: a server that takes 0.6 s to create an order, and a client that gives up after 0.3 s and tries again.
| Server behaviour | What the client saw | Orders created |
|---|---|---|
| No idempotency key | timeout, then 201 | 2 |
| Key recorded after the work | timeout, then 201 | 2 |
| Key claimed before the work, retry at once | timeout, then 409 | 1 |
| Key claimed before the work, retry 0.5 s later | timeout, then 201 (the stored reply) | 1 |
The fix is an idempotency key: the client generates a unique value (a UUID) for each logical operation and sends it in an Idempotency-Key header on every attempt. The server remembers the key together with the result, and a repeat returns the stored result instead of doing the work again.
The second row is the lesson. If the server only stores the key when it has finished, the retry arrives while the first request is still running, finds nothing, and does the work twice. The key must be claimed atomically before the work starts, and the claim is the database's job, not an if in application code. (The test server answered 409 while the first request was running. The next part shows a design where the duplicate waits and gets the stored reply instead.)
What a complete implementation needs
A table and an INSERT ... ON CONFLICT DO NOTHING are only the start. The rest is about where the transaction boundary is, what a second request sees, and what is left behind when the server dies.
CREATE TABLE idempotency_keys (
user_id bigint NOT NULL, -- keys belong to one caller, never to everybody
key text NOT NULL,
request_hash text NOT NULL, -- detects the same key used for a different request
locked_until timestamptz, -- lease for an in-progress claim (design B below)
status int, -- null while the first request has not finished
response jsonb,
created_at timestamptz NOT NULL DEFAULT now(),
PRIMARY KEY (user_id, key)
);
Design A: everything is in your own database. Claim, work and stored response share one transaction:
BEGIN; -- READ COMMITTED, the default
INSERT INTO idempotency_keys (user_id, key, request_hash) VALUES ($1, $2, $3)
ON CONFLICT (user_id, key) DO NOTHING; -- 1 row: you own the key; 0 rows: someone else does
INSERT INTO orders (...) VALUES (...); -- the business work
UPDATE idempotency_keys SET status = 201, response = $4 WHERE user_id = $1 AND key = $2;
COMMIT;
When zero rows were inserted, SELECT the stored row: compare its request_hash (a mismatch is 422) and replay its status and response. What happens in the cases that matter, checked on PostgreSQL 16:
| Situation | What the second request experienced | Orders created |
|---|---|---|
| A duplicate arrives while the first transaction is still running | its INSERT waited until the first committed (about a second here), inserted 0 rows, then read the stored reply | 1 |
The first transaction dies before committing (a crash simulated with ROLLBACK) | its INSERT succeeded and it did the work itself, because the claim vanished with the rollback | 1 |
| The first transaction committed, but the response never reached the client | the retry finds the stored reply and returns it | 1 |
Duplicate under REPEATABLE READ | the INSERT failed with could not serialize access due to concurrent update (SQLSTATE 40001) | 1 |
Four consequences:
- Because claim and work commit together, there is no half-finished state for anyone to find, so nothing needs recovering. A crash leaves nothing behind, and a committed order always has its stored response.
- Use the default
READ COMMITTEDfor this transaction. UnderREPEATABLE READorSERIALIZABLEthe duplicate fails with40001instead of waiting, which is also safe, but the code must catch that error and retry the whole request. - A waiting duplicate holds a database connection. Set a
lock_timeout(a few seconds) and, if it expires, answer409 ConflictwithRetry-After, so a slow request cannot pin the pool. - Keep the transaction to your own database. Calling a payment provider, sending an email or publishing a message inside it does not make those actions part of the transaction: if the transaction rolls back, the charge is still there.
Design B: the work reaches outside your database. Suppose the operation charges a payment provider. No local transaction can make the provider's charge and your order commit together, so some failure points will leave one done and the other not. The pattern is to make every step repeatable:
- Claim in its own short transaction, committed at once, with a lease:
INSERT ... (user_id, key, request_hash, locked_until) VALUES (..., now() + interval '30 seconds') ON CONFLICT DO NOTHING. Whilestatusis null and the lease is valid, a duplicate gets409withRetry-After. - Recover abandoned claims. If the server dies, the row stays "in progress" forever unless something takes it over. A retry may take the claim only after the lease expired, and exactly one retry wins:
UPDATE idempotency_keys SET locked_until = now() + interval '30 seconds'
WHERE user_id = $1 AND key = $2 AND status IS NULL AND locked_until < now()
RETURNING key; -- 1 row: you took over; 0 rows: wait
In a test with a one-second lease, the first request claimed, an immediate retry got zero rows from both the claim and the takeover, and a retry after the lease expired took over exactly once. Choose a lease longer than the slowest normal request, otherwise a slow but healthy request is taken over while it is still running.
- Give the outside system its own idempotency key, derived from yours (for example
order-<key>). A takeover cannot know whether the first attempt reached the provider before it died; passing the same key to the provider makes the repeat return the same charge instead of a new one. If the provider offers no such key, you can only look the charge up by your own reference before retrying, and there remains a window you must close by reconciliation. - Record progress (
charge_created,order_saved) so a takeover resumes after the last finished step rather than from the start, and finish by storingstatusandresponse. - Do other side effects through an outbox: insert a "send receipt" row in the same transaction as the order, and let a worker deliver it at least once. Consumers must tolerate a duplicate (see message queues and delivery guarantees).
| Where the server stops | What is left | What the retry does |
|---|---|---|
| before the claim | nothing | proceeds normally |
| design A, before commit | nothing (rolled back) | proceeds normally |
| design B, after the claim, before the work | an in-progress row | gets 409 until the lease ends, then takes over |
| design B, after the provider charged, before it was recorded | a charge at the provider; an in-progress row | takes over and repeats the call with the same provider key, which returns the same charge |
| after the commit, before the client heard | order and stored response | replays the stored response |
This is the honest limit: two systems cannot be made atomic by a local transaction. What you can build is at-least-once execution made harmless by idempotent steps, which behaves as exactly once from the outside.
Other rules: reject the same key with a different body (request_hash differs) with 422; scope keys to the caller (the user_id above) so one customer's key cannot collide with another's; and expire old keys after a day or so.
When may a client retry?
A 5xx response does not say whether a write took effect. The server may have committed the transaction and then failed to answer, and a gateway can return 502 or 504 for a request that the service behind it completed. Retrying a non-idempotent POST on such a response can therefore duplicate the operation. The rules for a client:
- Retry according to the method and the operation's guarantees: freely for safe methods (
GET,HEAD), forPUTandDELETE(idempotent by definition), and for aPOSTonly with an idempotency key. - Use bounded exponential backoff with jitter: wait a random time up to
min(cap, base * 2^attempt), stop after a maximum number of attempts or a total deadline, and honourRetry-After. Without jitter, every client retries at the same instant and an overloaded server never recovers. - Retry in one layer only. If the client, a gateway and a service each retry three times, one failure becomes up to 27 attempts.
| Response | Retry? | Notes |
|---|---|---|
| No response (timeout, connection reset) | only if idempotent or keyed | the outcome is unknown |
408 Request Timeout | yes | the server gave up waiting for the request and did not process it |
429 Too Many Requests | yes, after Retry-After | slow down, do not hammer |
500 Internal Server Error | with care: idempotent or keyed, few attempts | may be a bug that fails every time |
502 / 504 | same as a timeout | the outcome of a write is unknown |
503 Service Unavailable | yes, honouring Retry-After, with backoff and a limit | the server is overloaded or in maintenance |
501, other persistent 5xx | no | retrying cannot help |
409 Conflict | not blindly | read the current state, decide again, and send a new request; with an idempotency key a "still running" 409 can be retried with the same key |
412 Precondition Failed | no | fetch the resource again for its new ETag, merge, send again (section 9) |
400, 401, 403, 404, 405, 415, 422 | no | the same request gets the same answer; 401 may be retried once after refreshing credentials |
PUT and DELETE are idempotent by definition and need no key. Message consumers face the same problem and use the same cure (see message queues and delivery guarantees).
7. Pagination: do not use OFFSET for feeds
Never return an unbounded list. There are two common designs.
Offset paging (?limit=5&offset=10) is simple and allows jumping to page 7, but it asks the database to count rows from the start, and, worse, it is wrong when the list changes while the client reads it.
Cursor (keyset) paging (?limit=5&after=<cursor>) says "give me the items after this one". It stays fast on deep pages and does not repeat or skip items when rows are inserted ahead of the cursor. It is not a consistent snapshot of the whole list (see below).
An experiment: 20 posts, newest first, 5 per page. The client reads page 1, then 3 new posts arrive, then it reads page 2.
| Page 1 | Page 2 | Items seen twice | |
|---|---|---|---|
| OFFSET | 20, 19, 18, 17, 16 | 18, 17, 16, 15, 14 | 16, 17, 18 |
Keyset (id < 16) | 20, 19, 18, 17, 16 | 15, 14, 13, 12, 11 | none |
With offset paging the new rows pushed old ones down a page, so three items appeared twice (and a deletion would make items vanish). The keyset query:
SELECT id, created_at, title
FROM posts
WHERE (created_at, id) < ($1, $2) -- the last item of the previous page
ORDER BY created_at DESC, id DESC -- a unique, stable sort key
LIMIT 20;
Practical points:
- The sort key must be unique (add the id as a tie-breaker) and must have an index that matches it.
- Make the cursor an opaque string (for example base64 of the two values). Then you can change its content later, and clients do not build their own.
- Return the next cursor in the body (
"next": "eyJ...") or in aLinkheader (RFC 8288,rel="next"). Return nothing when there are no more items. - Cap
limit(for example 100) and give it a default. - Offset is fine for small, rarely changing lists and admin tables. For feeds and timelines use a cursor; for exports, read "What keyset paging does not promise" below. The news feed guide measures the speed difference on PostgreSQL.
What keyset paging does not promise
A cursor remembers a position in the sort order, not a frozen copy of the data. Each page is a fresh query, so changes made between pages still affect what the client sees. In a PostgreSQL 16 test with 20 posts sorted by updated_at DESC, id DESC, a client read page 1 (20 to 16), and then, before the rest, post 3 was updated (moving it to the top), post 10 was deleted and a new post was inserted with a sort key behind the cursor:
| Reading the rest | Result |
|---|---|
Each query on its own (READ COMMITTED) | 15, 14, 13, 21, 12, 11, 9, 8, ... post 3 never appeared (it moved ahead of the cursor), post 10 vanished (deleted), and the new post 21 appeared (inserted behind the cursor) |
All queries in one REPEATABLE READ READ ONLY transaction | 15, 14, ..., 3, 2, 1: the 20 posts as they were when the first page was read |
So keyset paging removes the duplicates and gaps caused by inserts at the top, and nothing more. When a client needs a complete, consistent dataset (an export, a reconciliation, a report), pick one of:
- An ordering that updates cannot change. Sort by an immutable key (
id, orcreated_at) rather thanupdated_at, so editing a row cannot move it across the cursor. Deletions can still remove items, so use soft-delete markers if clients must see them. - A snapshot boundary. Put an upper limit in the cursor (
created_at <= T, taken when the first page was served) so rows that arrive later are excluded. - A real database snapshot. Reading all pages in one
REPEATABLE READtransaction (or from an exported snapshot) gives the result above, but it keeps a transaction open, which delays cleanup of old row versions, so it suits a bounded job and not a client that may take an hour between pages. - A dedicated export job:
POST /exportsreturns202and a status resource (section 11); the server builds the file from a snapshot, and the client downloads it when it is ready.
8. Request and response shapes
- One naming style for JSON fields (
snake_caseorcamelCase), everywhere. - Dates and times as ISO 8601 strings in UTC (
2026-10-23T14:30:00Z); money as an integer of the smallest unit plus a currency code ({"amount": 1999, "currency": "USD"}), never a floating-point number. - Return the created or updated resource from
POSTandPATCH, so clients do not need a second request. - Prefer lists wrapped in an object:
{"items": [...], "next": "..."}. A bare array cannot grow anextfield or a total later without breaking clients. This is a trade-off, not a rule: a top-level array is perfectly valid for a small fixed list, or when paging information travels in headers (Link, RFC 8288) instead of the body. - Use
nullor omit a field consistently, and document which. - Reject unknown fields on write only if you must. On read, clients should ignore fields they do not know (the tolerant reader rule, section 10).
- Validate on the server whatever the client already checked.
9. Caching and concurrent updates with ETags
An ETag is an identifier for one version of a representation (often a hash or a version number). It enables two useful things.
Conditional reads save bandwidth. The client stores the ETag and sends it back as If-None-Match. If nothing changed, the server answers 304 Not Modified with no body. Measured with a list of 2,000 items:
| Request | Status | Body bytes |
|---|---|---|
First GET /items | 200 | 171,791 |
Repeat with If-None-Match | 304 | 0 |
(See caching strategies for where else to cache.)
Conditional writes stop lost updates. Two people open the same record. Both change it. The second save would silently overwrite the first, the same lost update as in the concurrency guide. The client sends the ETag it read in an If-Match header; if the resource changed since, the server refuses:
PUT /docs/9 HTTP/1.1
If-Match: "v1"
HTTP/1.1 412 Precondition Failed
In the test, both clients read version "v1"; the first PUT succeeded (200, now "v2") and the second, still carrying "v1", got 412. This is optimistic concurrency control: no locks are held while the user thinks, and a conflict is detected on save. A server can also insist on the header by answering 428 Precondition Required when it is missing. A database column with a version number or updated_at plays the same role as the ETag.
10. Versioning and compatibility
The best versioning strategy is not to need a new version. Changes that are safe (additive):
- adding a new endpoint, an optional request field or a new field in a response
- adding a new value to a response that clients treat as an open set (with documentation saying so)
Changes that break clients:
- removing or renaming a field or endpoint
- changing a field's type, format or meaning
- making an optional field required, or adding a new required request field
- changing status codes or the error format
- tightening validation
Clients should follow the tolerant reader rule (ignore unknown fields), and the server should follow the robustness rule in return: never remove or change what a published version promises.
When a breaking change is unavoidable, run both versions side by side. Common ways to name the version:
| Style | Example | Notes |
|---|---|---|
| In the path | /v2/orders | easiest to see, cache and route; the usual choice |
| In a header or media type | Accept: application/vnd.example.v2+json | cleaner URLs, harder to test in a browser |
| By date | Api-Version: 2026-10-01 | each client is pinned to the behaviour it first used |
Announce retirement early: mark deprecated endpoints in the documentation, send a Sunset header (RFC 8594) with the date, log which clients still call the old version, and contact them before you switch it off.
11. Long-running operations
If the work takes more than a second or two, do not hold the connection open. Accept it and let the client check:
POST /reports HTTP/1.1
HTTP/1.1 202 Accepted
Location: /reports/jobs/31
GET /reports/jobs/31
{ "status": "running", "progress": 40 }
GET /reports/jobs/31
HTTP/1.1 303 See Other
Location: /reports/18
The client polls the status resource (with a Retry-After hint to keep polling polite) or gets a webhook when the job ends. Combined with an idempotency key, a retried POST returns the same job instead of starting a second one. Behind the scenes the job usually sits on a queue.
12. Security and limits in the contract
- Use HTTPS only (see TLS and HTTPS). Redirecting
httptohttpsis not enough for an API: clients may already have sent a secret. - Authenticate every request and authorise every object: knowing
/orders/42exists must not let user B read user A's order (the most common API flaw is a missing object-level check). The authentication guide covers sessions, tokens and OAuth. - Rate limit per client and return
429withRetry-Afterand, if you like, the remaining quota in headers (see the rate limiter guide). - Limit sizes: request body, page size, number of ids per call, and time per request.
- Set
Content-Typeon every response and reject requests with the wrong one (415). - Do not put secrets in URLs. URLs end up in logs, browser history and
Refererheaders.
13. Describing the API
Write the contract down in a machine-readable form such as an OpenAPI document. From it you get reference pages, mock servers, generated client libraries, request validation, and a way to detect breaking changes automatically in a pull request. Pair it with examples for the common flows (create, list with a cursor, handle an error, retry with an idempotency key) because developers read examples before reference pages. Contract tests that run the real server against the spec keep the two from drifting.
14. Common mistakes, and trade-offs that are not mistakes
Mistakes (these break clients or lose data):
- One big
POST /apithat takes an action name, or a random mix of styles in one API. - Returning
200with{"success": false}. - A retried
POSTthat is not protected by an idempotency key, a key stored only after the work is done, or a claim that is never recovered after a crash. - Retrying a write on a
5xxas if it proved the write failed. - Offset paging on a list that changes, and no cap on
limit. - Different error shapes in different endpoints.
- Floating-point money, local times without a zone, ids that are guessable.
- Missing object-level authorisation (anyone logged in can read
/orders/<any id>). - Breaking changes inside an existing version.
- Saving without
If-Match, so concurrent edits silently overwrite each other.
Trade-offs (conventions with good reasons, not rules of REST; decide, document and stay consistent):
- Plural or singular resource names.
- Verbs in action paths (
POST /orders/42/cancel) or a state change throughPATCH. - A list wrapped in an object (room to grow) or a bare array (fine when you will never need metadata, or it travels in headers).
- Offset paging for small admin lists, where its simplicity wins.
15. Things to mention in an interview
- Start from the resources and the operations, then choose URLs and methods; mention safe and idempotent and why retries depend on them.
- Use status codes precisely and give the 401 versus 403 and 404 versus 410 distinctions.
- Design for retries: idempotency keys for
POST, claimed atomically before the work, with the claim and the result in the same transaction when you can. Be able to say what happens if the server crashes at each step, and that a payment provider needs its own idempotency key. Retry by method semantics, with bounded backoff and jitter. - Paginate with cursors and explain what goes wrong with offsets.
- Mention concurrency control with
ETag/If-Matchor a version column. - Mention compatibility: additive changes, tolerant readers, versioning, deprecation with a
Sunsetdate. - Mention operations: rate limits, request ids, timeouts, long-running jobs with
202, and OpenAPI.
Questions interviewers like to add:
- "
PUTorPATCH?"PUTreplaces the whole resource and is idempotent;PATCHchanges parts and must be designed to be idempotent. - "A client says it was charged twice. How could that happen and how do you prevent it?" A retry after a timeout or a
5xxfor a write that had actually committed. An idempotency key with an atomic claim, the same key passed to the payment provider, and a recovery rule for claims abandoned by a crash. - "How do you let a client read all 10 million records?" A cursor over an indexed, unique, immutable sort key and a page size cap. A cursor is not a snapshot, so if the client needs a consistent copy, add a snapshot boundary or use an export job (
202) built from a database snapshot. - "REST or GraphQL or gRPC?" REST for simple public resources and caching through HTTP; GraphQL when clients need to choose fields across many resources; gRPC for internal low-latency service-to-service calls with a typed contract.
- "How do you change a field name without breaking clients?" Add the new field, keep the old one, announce the deprecation, remove it in a later version.
Quick recap
- Model resources with consistently named nouns (plural is the usual convention); the method is the verb and the status code is the outcome.
- Safe and idempotent decide what may be retried;
POSTis neither. - Never return
200for an error; use one error shape (RFC 9457) everywhere. - A retried
POSTcreated two orders in the test; an idempotency key claimed before the work created one, and a key stored only afterwards still created two. A complete design also fixes the transaction boundary, recovers abandoned claims with a lease, and gives outside services their own key. A5xxnever tells you whether a write happened. - Offset paging repeated three items when posts arrived between pages; keyset paging repeated none, but it is not a snapshot: updates to the sort key and deletions still change what a client sees, so a consistent export needs an immutable order, a snapshot or an export job.
ETagwithIf-None-Matchturned a 171,791-byte response into a304with no body, andIf-Matchturned a lost update into a412.- Add, never change or remove; version only when you must, and retire old versions with notice.
- Long jobs return
202and a status resource; write the contract in OpenAPI.
Sources
- R. Fielding et al., RFC 9110: HTTP Semantics. Methods, safe and idempotent, status codes, conditional requests and entity tags.
- M. Nottingham, E. Wilde, S. Dalal, RFC 9457: Problem Details for HTTP APIs.
- M. Nottingham, RFC 8288: Web Linking (the
Linkheader) and E. Wilde, RFC 8594: The Sunset HTTP Header Field. - M. Nottingham and R. Fielding, RFC 6585: Additional HTTP Status Codes (
428,429). - P. Hoffman and J. Snell, RFC 7396: JSON Merge Patch, and P. Bryan and M. Nottingham, RFC 6902: JSON Patch.
- Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures, chapter 5 (REST), 2000.
- Martin Fowler, Richardson Maturity Model.
- Stripe documentation, Idempotent requests. A widely copied design for idempotency keys.
- Google, API Improvement Proposals, for example AIP-158 on pagination.
- OpenAPI Initiative, OpenAPI Specification.
Practise this topic: Networking & APIs