API design: contracts that are safe to call, retry and change

An API is a promise to everyone who calls it. Once apps depend on it, it's hard to change, so the decisions you make on day one last for years. This module covers how to shape resources and errors, page through long lists without losing items, make retries safe, evolve without breaking clients, and when gRPC or GraphQL fit better than REST.

1. The idea

Most public and product APIs are REST: you act on resources (nouns) using a small set of HTTP methods (verbs).

"Safe to repeat" is idempotency: doing it twice has the same effect as doing it once. It matters because networks fail after the server acted but before the client heard back, so clients retry, and a non-idempotent retry can charge a card twice.

Shaping the request

• Path identifies the resource: /events/42/tickets. Use plural nouns and nesting for ownership; never verbs (/getTickets).
• Query parameters are optional filters, sorting and paging: ?section=VIP&sort=-price&limit=20.
• Body carries the data being created or changed.
• Headers carry metadata: Authorization, Idempotency-Key, If-Match, caching headers.
• Identity comes from the token, never from a userId in the body. The server then checks the caller may touch this resource (authorization).

2. How it works

Paging through a list that keeps changing

Every list that grows (posts, orders, messages) needs pagination. There are two common ways. Press Play to see what happens when new posts arrive while a user scrolls.

-- Offset: simple, lets users jump to page 7, but drifts and gets slow deep down (the DB still walks the skipped rows)
SELECT * FROM posts ORDER BY created_at DESC LIMIT 20 OFFSET 40;

-- Cursor (keyset): stable under inserts, fast at any depth with an index on (created_at, id)
SELECT * FROM posts WHERE (created_at, id) < (:last_created_at, :last_id)
ORDER BY created_at DESC, id DESC LIMIT 20;

Return the cursor as an opaque string ("next": "eyJ0IjoiMjAyNi0x...") so you can change what's inside it later. Always cap limit.

Errors that clients can act on

Use the right status class (4xx: the caller must change something; 5xx: our fault, maybe retry) and one error shape everywhere. RFC 9457 ("Problem Details") standardises it:

HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{"type": "https://api.example.com/errors/seat-taken",
 "title": "Seat no longer available",
 "status": 409,
 "detail": "Seat 14C was booked by someone else.",
 "instance": "/events/42/bookings"}

Making POST safe to retry

The client generates a unique idempotency key (a random UUID) per logical operation and sends it with every attempt. The server stores the key with the result; a repeat of the same key returns the stored result instead of acting again. Stripe popularised this (keys up to 255 characters, kept for at least 24 hours), and the IETF is standardising the Idempotency-Key header (still a draft in October 2026). Try it in section 3.

Long-running work: 202 and a job

If a request starts something slow (a video encode, a report), don't hold the connection open. Return 202 Accepted with a job resource, Location: /jobs/123, and let the client poll it, or call the client back with a webhook when it's done. Sign webhooks (an HMAC of the body with a shared secret) so receivers can verify they came from you, and expect them to arrive more than once.

Changing an API without breaking clients

• Safe changes: adding endpoints, adding optional fields, adding new values clients are told to ignore.
• Breaking changes: renaming or removing fields, changing types or meanings, making optional input required.
• Versioning: breaking changes go in a new version, usually in the path (/v2/), sometimes in a header or a dated version (Stripe-Version: 2026-09-30). Keep the old version running with a published end date.

Nine principles to apply out loud

Don't recite these; show them in the endpoints you write. I'll add an idempotency key here so a retry can't double-book the seat scores; a memorised list doesn't.

1. Resources, not actions: GET /users/7/bookings, not /getUserBookings.
2. Consistency: the same names, parameters and response shapes on every endpoint.
3. Least surprise: GET never changes data; errors are never hidden inside a 200.
4. Stateless: every request carries its token and inputs, so any server can answer.
5. Safe retries: idempotency keys on payments, bookings and orders.
6. Paginate every growing list, with a maximum page size.
7. Secure by default: authentication unless marked public, a per-resource permission check, rate limits.
8. Evolve without breaking: add fields freely; rename or remove only in a new version.
9. Actionable errors: the right status class, a machine-readable code and a human message.

3. Try it yourself

Retry a payment over a flaky network

Each click sends POST /payments {"amount": 50}. With "lose the response" on, the server charges the card but the reply never reaches the app, so the app retries. Try it with and without an idempotency key.

Spot the API smells

4. REST, gRPC or GraphQL?

Real-time push (WebSockets, server-sent events) is a different problem: Module 19.

5. In real systems

• Describe the API in a schema: OpenAPI (version 3.2 in October 2026) for REST, .proto files for gRPC, an SDL schema for GraphQL. Generate docs, client libraries and request validation from it, and review changes to it like code.
• Put cross-cutting rules in a gateway: an API gateway (Module 08) handles authentication, rate limits (returning 429 Too Many Requests with Retry-After), request size limits and logging, so each service doesn't reimplement them.
• Auth: end users usually present a short-lived signed token (a JWT from an OAuth 2.0 / OpenID Connect login), verified without a database call; services use their own credentials (Module 26). API keys suit server-to-server integrations, not end users.
• Deadlines and timeouts: gRPC lets callers set a deadline that travels with the request through every downstream call, so work stops when the caller has given up.
• Optimistic concurrency over HTTP: GET returns an ETag; the client sends If-Match: "v7" on its PUT; the server answers 412 Precondition Failed if someone changed it meanwhile (Module 17).
• Style guides worth borrowing: Google's API design guide, Microsoft's REST guidelines and Zalando's RESTful guidelines.

The technologies up close

6. Remember it

7. Common mistakes

8. Design exercise (25 minutes)

1. Design the API for a food delivery app: browse restaurants near me, view a menu, place an order, track the order. Write each endpoint with method, path, key inputs and response.
2. Make it safe: which endpoints need an idempotency key? Which lists need pagination, and offset or cursor?
3. Errors: write the response for "restaurant closed" and for "payment declined". Which status codes?
4. Evolve it: the product now wants scheduled orders. Add it without breaking existing clients.
5. Write it down: your three favourite rules from this page in your design notebook.

9. Self-check quiz

10. Go deeper

11. Under the hood (optional)

How API payloads are really encoded, evolved and compressed. Not needed for most interviews; open it when you want to know how the products really do it. All the deep dives are listed on the Under the hood page.