Foundations 0/8

Lesson 4 of 8

API design

Define an order API's requests, responses, errors, versioning, retries and pagination, and choose between REST, gRPC, GraphQL and real-time channels.

2,216 words · 10 min read Key topic Useful background: How the web works

An API contract defines what a caller can rely on

An API contract defines the operations one program exposes and the behavior a caller may rely on. It includes request and response data, authorization, errors and the effects of repetition. A caller can receive no response even though the server committed a change, so a complete contract must cover uncertain outcomes as well as ordinary success.

For an HTTP API, the resource identifies what the operation concerns, while the method expresses its semantics. GET /orders/ord_7 retrieves a representation. POST /orders submits data for processing and may create a resource. A GET must not request a state change such as confirming an order. Clients and intermediaries may prefetch or repeat reads, so attaching a confirmation to GET can apply it without an intentional confirmation action. A create operation needs an explicit retry contract if repeating it could create another order.

Specify data meaning before choosing field names. A monetary amount needs a currency and an exact unit. An identifier needs a scope and ownership rule. The authenticated account determines which orders a caller may access, including on a retry or a later page of results. Returning an order id is useful only if the contract also states whether it identifies an accepted, pending or failed operation.

Two recurring multi-request problems illustrate these obligations. A lost create response can cause a duplicate order when the client retries. A collection changed between page requests can cause repeated or skipped rows. Idempotency keys give a logical operation a stable identity, while cursor pagination gives traversal a stable ordering boundary. Each mechanism preserves a different promise across requests.

Specify success, validation and authorization together

An order API, including the responses for retried creates
OperationRequestContract
Read an orderGET /orders/ord_7200 with an authorized representation; a missing or inaccessible id returns the same 404, so the response does not reveal which orders exist.
Create an orderPOST /orders with an Idempotency-Key header201 with id and Location on first success; the same key and payload later return the stored result.
List ordersGET /orders?page_size=20&page_token=…Stable descending order, a bounded page and an opaque continuation token.
Reject invalid inputPOST with a negative amount400 with a stable machine-readable error code and the offending field.
Retry while the first attempt is still runningSame key and payload; the first request has not finished409 Conflict; the client retries after the first attempt completes.
Reuse a key for a different requestExisting key with a different amount422 Unprocessable Content; no second order is created.

The two retry rows use different codes because they describe different problems. A 409 says the request conflicts with the resource’s current state, here an operation still in progress, and the same request will succeed later. A 422 says the server understood the request but cannot process it as sent, and repeating it unchanged will never succeed. These are the codes the IETF HTTPAPI working group’s Idempotency-Key header draft recommends, along with 400 when a required key is missing. Authorization runs on every request, including requests that carry a page token or replay a stored result.

Continue after a key rather than a shifting position

Pagination divides a collection into bounded responses so a client does not request or render the entire dataset at once. It requires a total order: every row must have a determinate position relative to another row. An immutable creation timestamp plus a unique id can provide that order even when several rows share a timestamp.

Offset pagination names a position in the collection as it exists when the next query runs. After page one returns two rows, page two skips the first two rows of the current collection. If a new row appears at the front, the old second row moves to position three and is returned again. Deleting a preceding row moves an unseen row into the skipped region. Offset pagination is simple and can support direct page selection, but changing data makes these positions unstable.

Cursor pagination, also called keyset pagination, names an ordering boundary from the previous response. If page one returns immutable ids 106 and 105 in descending order, page two requests ids below 105. Inserting 107 does not change that predicate. A matching index can seek to the boundary and scan the next bounded group, avoiding the work of scanning a large skipped offset.

The cursor must include every part of the order. With a timestamp and id, the next query uses the same tuple comparison and sort direction. A timestamp-only predicate skips remaining rows that share the boundary timestamp. Changing an ordering field can also move a row across a previously read boundary, which is why the ordering keys must be immutable.

A cursor preserves progress through that order; it does not create a snapshot. New rows before the boundary will not appear during the traversal, and deleted rows disappear. An export requiring a consistent historical view needs a snapshot or versioned dataset with an explicit lifetime. Choose that stronger guarantee when the product requires it, because retaining historical state adds storage and operational work.

Change the collection between requests

Does the second page repeat or skip an order when a row is inserted or deleted after the first page, and does a retried create after a lost response place a second order? Compare offset with cursor pagination, and a create with an operation key against one without.

Current collection, newest first

106105104103102101
Last returned page
None yet
Next boundary
Skip 0 rows
IDs seen in order
None yet

Read a page, change the collection, then read again. Each page contains at most two IDs.

Create an order after a lost response

Committed orders: 0

No request has been sent.

Serial in-memory model. Production needs account-scoped durable keys, atomic commits, authorization and opaque page tokens.

A cursor survives the insertion because its predicate names a key rather than a position. An operation key survives the lost response because the server stored the first result under it, so the retry returns that result instead of running the create again.

Put the continuation predicate into the query

In SQL, the cursor becomes a row comparison on the same columns as the sort. The server reads one row more than the page size: if that extra row exists, there is a next page, and the last row actually returned becomes the next cursor.

-- First page of an account's orders, newest firstSELECT id, created_at, total_centsFROM ordersWHERE account_id = $1ORDER BY created_at DESC, id DESCLIMIT 21;  -- page size 20, plus one row to detect a next page-- Next page: continue strictly after the last row returnedSELECT id, created_at, total_centsFROM ordersWHERE account_id = $1  AND (created_at, id) < ($2, $3)ORDER BY created_at DESC, id DESCLIMIT 21;-- The index that lets both queries seek instead of scanningCREATE INDEX orders_account_created_id  ON orders (account_id, created_at DESC, id DESC);
Keyset pagination in PostgreSQL

Production tokens should be opaque to callers and bound to the original account, filters and sort order. One implementation signs a serialized token and rejects tampering or changed query parameters. A token identifies where traversal continues; the server must separately authorize the request, so validate its structure and apply the caller’s permissions again.

For create retries, store a unique record keyed by account and operation key. In one database transaction, record the key with a fingerprint of the request, create the order and store the result. A retry with a matching fingerprint returns the stored result, one with a different fingerprint returns 422, and one that arrives while the first transaction is still running returns 409. Concurrent first attempts contend on the unique key, so only one can create the order. Document how long keys remain valid so a retry after expiry is not mistaken for a guaranteed replay.

If creating the order also triggers an external payment, a database transaction alone cannot atomically commit both systems. Pass a stable provider operation key, record pending states and reconcile uncertain outcomes. The transactional outbox lesson covers durable downstream work.

REST, gRPC, GraphQL and real-time channels

The contract questions stay the same across protocols, but each protocol fits a different kind of caller. The first three serve request and response calls; the last three push updates to a client without it asking for each one.

Common API styles and when each fits
StyleHow it worksFitsCosts
REST over HTTP with JSONResources named by URLs, operations by HTTP methods, readable JSON bodiesPublic and browser-facing APIs; anything that benefits from HTTP caches and toolingVerbose payloads; clients may need several calls or receive fields they do not use
gRPCServices and messages defined in Protocol Buffers, generated clients, binary messages over HTTP/2, unary or streaming callsInternal service-to-service calls where both sides share the schemaBrowsers need a proxy such as gRPC-Web; binary traffic is harder to inspect
GraphQLOne endpoint and a typed schema; each query names exactly the fields it needsMany client screens that need different shapes of related dataShared HTTP caching is harder; naive field resolvers cause one database query per item; queries need cost limits
WebSocketsAn HTTP upgrade turns the connection into a long-lived, two-way message channelChat, multiplayer games and collaborative editingStateful connections pin clients to servers; reconnection and missed-message recovery are the application’s job
Server-sent eventsThe server holds an HTTP response open and streams text events; the browser reconnects and reports the last event idOne-way live updates such as notifications, scores and streamed model outputServer to client only; text only
Long pollingThe server holds each request until data exists or a timeout passes, then the client asks againLow update rates, or networks that block streamingOne full request per update and a gap between updates

Evolve a contract without breaking callers

Clients are deployed separately from the server, and mobile apps stay installed long after a new release. A change is backward compatible when every existing client keeps working: adding an optional request field, a new response field that clients ignore, or a new endpoint. Removing or renaming a field, changing its type, units or meaning, or making an optional input required breaks existing clients. Ship a breaking change as a new version, often a /v2/ path or a version header, and keep the old version running until its traffic falls to zero.

Errors are part of the contract too. Return one error shape across every endpoint so a client writes its handling once. RFC 9457 defines a standard one, application/problem+json, with a type URI identifying the error, a human-readable title and detail, the status code and room for extra fields such as the invalid parameter. A stable machine-readable error type lets clients branch on the error without parsing English text.

Every request carries its own credential, usually a session cookie or a bearer token in the Authorization header, because HTTP keeps no session between requests. The server derives the caller’s account from that credential and never from an account id in the request body or path, then checks that the account may act on the named resource.

What stays true

A cursor advances strictly through a stable total order; an operation key maps one account and request payload to at most one committed logical create.

Every cursor page contains only keys beyond the previous boundary, so a previously returned immutable key cannot reappear. For creation, the unique operation record and atomic commit serialize competing attempts. Both rules depend on stable ordering keys and durable transactions.

Bound the work and state behind the contract

Pagination and retry costs
MechanismCostCondition
Indexed keyset pageA seek to the boundary plus the returned rowsAn index matching the filter and sort order; extra filters and row fetches add work.
Deep offset pageScans every skipped entry as well as the returned rowsLarger offsets cost more and are sensitive to preceding insertions or deletions.
Durable retry recordsStorage for every key retainedStore request fingerprints and results for the documented retry interval; delete expired records.
Snapshot traversalA stable historical viewRetaining versions or snapshot state adds storage and operational cost.
A second API versionTwo versions to run, test and secureUntil the last client of the old version migrates.

Requests that behave differently on the second attempt

  1. Use a timestamp without a unique tie-breaker.

    Where it breaks
    Four orders share a timestamp; a “strictly older” cursor skips two of them.
    The fix
    Order and filter by the same immutable (created_at, id) tuple.
  2. Generate a new operation key on every retry.

    Where it breaks
    The first create commits, its response is lost, and the retry creates a second order.
    The fix
    Keep the key stable for one logical operation and persist it until the outcome is resolved.
  3. Replay a key without checking its payload or owner.

    Where it breaks
    A reused key for a different amount returns an unrelated result, or another account retrieves it.
    The fix
    Scope records to the authenticated account, compare the request fingerprint and return 422 on a mismatch.
  4. Treat a page token as proof of access.

    Where it breaks
    An old token still lists private orders after the caller loses membership.
    The fix
    Recheck authorization and bind the token to its filters and scope on each request.
  5. Rename a response field in place.

    Where it breaks
    Last year’s mobile release reads total and crashes when the field becomes total_cents.
    The fix
    Add the new field beside the old one, migrate clients, and remove the old field only in a new version.

Carry the contract into storage and retries

Related topics

Further reading