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:

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

3. Methods and their guarantees

Two properties from the HTTP specification decide how a client may use a method:

MethodUseSafeIdempotentTypical success
GETread a resource or a listyesyes200
HEADlike GET, headers onlyyesyes200
POSTcreate a resource or start an actionnono201 + Location, or 202
PUTreplace a resource completelynoyes200 or 204
PATCHchange part of a resourcenonot guaranteed200 or 204
DELETEremove a resourcenoyes204 (or 200)

Notes that trip people up:

4. Status codes: say what happened

Choose the most specific code that fits; clients branch on the code before they read the body.

CodeMeaningUse it when
200 OKsuccess with a bodya read or an update that returns the resource
201 Creatednew resourceafter POST; add a Location header with its URL
202 Acceptedwork queued, not doneslow operations (section 11)
204 No Contentsuccess, nothing to returnDELETE, or an update that returns nothing
301 / 308moved permanentlya resource has a new URL
304 Not Modifiedyour cached copy is still goodconditional GET (section 9)
400 Bad Requestthe request is malformedbad JSON, a missing field, a wrong type
401 Unauthorizednot authenticatedno or invalid credentials; send WWW-Authenticate
403 Forbiddenauthenticated, not allowedthe user may not do this
404 Not Foundno such resourcealso used to hide that a private resource exists
405 Method Not Allowedthe method is not supported heresend an Allow header
409 Conflictclashes with the current stateduplicate unique value, request already running; the client usually has to refresh its view of the state (section 6)
410 Goneexisted, removed on purposeretired resources
412 Precondition Failedan If-Match condition failedsomeone else changed it first (section 9)
415 Unsupported Media Typecannot read this Content-TypeJSON expected, got XML
422 Unprocessable Contentwell-formed but invalidbusiness-rule validation errors
429 Too Many Requestsrate limitedsend Retry-After (see the rate limiter guide)
500 / 502 / 503 / 504server, gateway, overload, timeout503 with Retry-After during overload or maintenance

Two rules matter more than any single code:

  1. Never return 200 with an error inside. Monitoring, caches, retries and client libraries all trust the status line.
  2. 4xx means the request needs to change, 5xx means 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: some 4xx codes are worth retrying and no 5xx tells 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" }]
}

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 behaviourWhat the client sawOrders created
No idempotency keytimeout, then 2012
Key recorded after the worktimeout, then 2012
Key claimed before the work, retry at oncetimeout, then 4091
Key claimed before the work, retry 0.5 s latertimeout, 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:

SituationWhat the second request experiencedOrders created
A duplicate arrives while the first transaction is still runningits INSERT waited until the first committed (about a second here), inserted 0 rows, then read the stored reply1
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 rollback1
The first transaction committed, but the response never reached the clientthe retry finds the stored reply and returns it1
Duplicate under REPEATABLE READthe INSERT failed with could not serialize access due to concurrent update (SQLSTATE 40001)1

Four consequences:

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:

  1. 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. While status is null and the lease is valid, a duplicate gets 409 with Retry-After.
  2. 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.

  1. 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.
  2. Record progress (charge_created, order_saved) so a takeover resumes after the last finished step rather than from the start, and finish by storing status and response.
  3. 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 stopsWhat is leftWhat the retry does
before the claimnothingproceeds normally
design A, before commitnothing (rolled back)proceeds normally
design B, after the claim, before the workan in-progress rowgets 409 until the lease ends, then takes over
design B, after the provider charged, before it was recordeda charge at the provider; an in-progress rowtakes over and repeats the call with the same provider key, which returns the same charge
after the commit, before the client heardorder and stored responsereplays 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:

ResponseRetry?Notes
No response (timeout, connection reset)only if idempotent or keyedthe outcome is unknown
408 Request Timeoutyesthe server gave up waiting for the request and did not process it
429 Too Many Requestsyes, after Retry-Afterslow down, do not hammer
500 Internal Server Errorwith care: idempotent or keyed, few attemptsmay be a bug that fails every time
502 / 504same as a timeoutthe outcome of a write is unknown
503 Service Unavailableyes, honouring Retry-After, with backoff and a limitthe server is overloaded or in maintenance
501, other persistent 5xxnoretrying cannot help
409 Conflictnot blindlyread 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 Failednofetch the resource again for its new ETag, merge, send again (section 9)
400, 401, 403, 404, 405, 415, 422nothe 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 1Page 2Items seen twice
OFFSET20, 19, 18, 17, 1618, 17, 16, 15, 1416, 17, 18
Keyset (id < 16)20, 19, 18, 17, 1615, 14, 13, 12, 11none

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:

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 restResult
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 transaction15, 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:

8. Request and response shapes

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:

RequestStatusBody bytes
First GET /items200171,791
Repeat with If-None-Match3040

(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):

Changes that break clients:

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:

StyleExampleNotes
In the path/v2/orderseasiest to see, cache and route; the usual choice
In a header or media typeAccept: application/vnd.example.v2+jsoncleaner URLs, harder to test in a browser
By dateApi-Version: 2026-10-01each 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

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):

  1. One big POST /api that takes an action name, or a random mix of styles in one API.
  2. Returning 200 with {"success": false}.
  3. A retried POST that 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.
  4. Retrying a write on a 5xx as if it proved the write failed.
  5. Offset paging on a list that changes, and no cap on limit.
  6. Different error shapes in different endpoints.
  7. Floating-point money, local times without a zone, ids that are guessable.
  8. Missing object-level authorisation (anyone logged in can read /orders/<any id>).
  9. Breaking changes inside an existing version.
  10. 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):

15. Things to mention in an interview

Questions interviewers like to add:

Quick recap

  1. Model resources with consistently named nouns (plural is the usual convention); the method is the verb and the status code is the outcome.
  2. Safe and idempotent decide what may be retried; POST is neither.
  3. Never return 200 for an error; use one error shape (RFC 9457) everywhere.
  4. A retried POST created 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. A 5xx never tells you whether a write happened.
  5. 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.
  6. ETag with If-None-Match turned a 171,791-byte response into a 304 with no body, and If-Match turned a lost update into a 412.
  7. Add, never change or remove; version only when you must, and retire old versions with notice.
  8. Long jobs return 202 and a status resource; write the contract in OpenAPI.

Sources

  1. R. Fielding et al., RFC 9110: HTTP Semantics. Methods, safe and idempotent, status codes, conditional requests and entity tags.
  2. M. Nottingham, E. Wilde, S. Dalal, RFC 9457: Problem Details for HTTP APIs.
  3. M. Nottingham, RFC 8288: Web Linking (the Link header) and E. Wilde, RFC 8594: The Sunset HTTP Header Field.
  4. M. Nottingham and R. Fielding, RFC 6585: Additional HTTP Status Codes (428, 429).
  5. P. Hoffman and J. Snell, RFC 7396: JSON Merge Patch, and P. Bryan and M. Nottingham, RFC 6902: JSON Patch.
  6. Roy Fielding, Architectural Styles and the Design of Network-based Software Architectures, chapter 5 (REST), 2000.
  7. Martin Fowler, Richardson Maturity Model.
  8. Stripe documentation, Idempotent requests. A widely copied design for idempotency keys.
  9. Google, API Improvement Proposals, for example AIP-158 on pagination.
  10. OpenAPI Initiative, OpenAPI Specification.

Practise this topic: Networking & APIs

More guides