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
| Operation | Request | Contract |
|---|---|---|
| Read an order | GET /orders/ord_7 | 200 with an authorized representation; a missing or inaccessible id returns the same 404, so the response does not reveal which orders exist. |
| Create an order | POST /orders with an Idempotency-Key header | 201 with id and Location on first success; the same key and payload later return the stored result. |
| List orders | GET /orders?page_size=20&page_token=… | Stable descending order, a bounded page and an opaque continuation token. |
| Reject invalid input | POST with a negative amount | 400 with a stable machine-readable error code and the offending field. |
| Retry while the first attempt is still running | Same key and payload; the first request has not finished | 409 Conflict; the client retries after the first attempt completes. |
| Reuse a key for a different request | Existing key with a different amount | 422 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
- 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);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.
| Style | How it works | Fits | Costs |
|---|---|---|---|
| REST over HTTP with JSON | Resources named by URLs, operations by HTTP methods, readable JSON bodies | Public and browser-facing APIs; anything that benefits from HTTP caches and tooling | Verbose payloads; clients may need several calls or receive fields they do not use |
| gRPC | Services and messages defined in Protocol Buffers, generated clients, binary messages over HTTP/2, unary or streaming calls | Internal service-to-service calls where both sides share the schema | Browsers need a proxy such as gRPC-Web; binary traffic is harder to inspect |
| GraphQL | One endpoint and a typed schema; each query names exactly the fields it needs | Many client screens that need different shapes of related data | Shared HTTP caching is harder; naive field resolvers cause one database query per item; queries need cost limits |
| WebSockets | An HTTP upgrade turns the connection into a long-lived, two-way message channel | Chat, multiplayer games and collaborative editing | Stateful connections pin clients to servers; reconnection and missed-message recovery are the application’s job |
| Server-sent events | The server holds an HTTP response open and streams text events; the browser reconnects and reports the last event id | One-way live updates such as notifications, scores and streamed model output | Server to client only; text only |
| Long polling | The server holds each request until data exists or a timeout passes, then the client asks again | Low update rates, or networks that block streaming | One 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
| Mechanism | Cost | Condition |
|---|---|---|
| Indexed keyset page | A seek to the boundary plus the returned rows | An index matching the filter and sort order; extra filters and row fetches add work. |
| Deep offset page | Scans every skipped entry as well as the returned rows | Larger offsets cost more and are sensitive to preceding insertions or deletions. |
| Durable retry records | Storage for every key retained | Store request fingerprints and results for the documented retry interval; delete expired records. |
| Snapshot traversal | A stable historical view | Retaining versions or snapshot state adds storage and operational cost. |
| A second API version | Two versions to run, test and secure | Until the last client of the old version migrates. |
Requests that behave differently on the second attempt
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.
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.
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.
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.
Rename a response field in place.
- Where it breaks
- Last year’s mobile release reads
totaland crashes when the field becomestotal_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
- Idempotency keys →
Durable keys, replayed results and retry races.
- Indexes →
Build an index that matches the continuation predicate.
- Transactional outbox →
Commit an order and its downstream work together.
Further reading
- Google AIP-158: Pagination Page sizes, opaque continuation tokens and compatibility guidance. google.aip.dev (opens in a new tab)
- RFC 9110: HTTP Semantics HTTP methods, idempotent semantics and the conditions for automatic retries. rfc-editor.org (opens in a new tab)
- IETF draft: The Idempotency-Key HTTP header A working-group draft, not yet an RFC: the header, fingerprints and the 400, 409 and 422 error cases. datatracker.ietf.org (opens in a new tab)
- RFC 9457: Problem Details for HTTP APIs A standard JSON shape for error responses. rfc-editor.org (opens in a new tab)
- gRPC: Introduction Service definitions in Protocol Buffers and generated clients. grpc.io (opens in a new tab)
- Google API Improvement Proposals Google's public API style rules: resources, methods, pagination, errors. google.aip.dev (opens in a new tab)