Building Software
Sections

Contents Section 6, Design

Interfaces and APIs

Designing the contracts between parts of a system and between systems: shapes, errors, versions and limits.

Section 6 of 9, subsection 3 of 6. Depth: do. An 8-minute read.

Mistakes to catch in review

  1. A breaking change to a public API, such as a renamed field or changed type, shipped without a version or a migration path.

  2. A list endpoint with no pagination or limit that works in development and times out on real data.

  3. Error responses whose shape differs from one endpoint to the next, or that leak stack traces to clients.

The promise an API makes

A customer reports that invoice totals sometimes show a rounding error, and you give the bug to an agent. It finds that the API returns totals as strings like "19.99" and decides, reasonably, that money should be an integer number of cents. It changes the response of GET /v1/invoices/{id} so total is now 1999, updates the web app to divide by 100, and the tests pass.

The API also has clients you didn't write. A customer's billing script does this:

TypeScript
const invoice = await res.json();
row.amount = `$${parseFloat(invoice.total).toFixed(2)}`;

parseFloat(1999) returns 1999, so the script now reports an invoice of $1999.00. The script keeps running and reports a total a hundred times too large. Your mobile app, whose decoder expects total to be a string, fails to decode the whole invoice and shows an error screen to every user who hasn't updated. The agent fixed a real bug and broke two clients, one loudly and one silently, and nothing in your test suite could see either.

An API is a promise to code you don't control.

What the contract includes

The contract is everything a client can observe and might rely on. Field names and types are the obvious part. So are the status codes, the shape of error bodies, whether a field can be null, the order items come back in, the default page size, and how long a request takes. Hyrum Wright's observation, known as Hyrum's Law, is that with enough users, every observable behavior of a system ends up depended on by somebody, whatever the documentation said.

This matters because a client is often out of your reach. A mobile app version stays installed on phones for months after you ship a new one. A customer's script runs from a cron job that nobody at that company has looked at in a year. You can't update those clients, so the only safe changes are the ones they can survive unchanged.

Compatible and breaking changes

The test for any change is one question: would a client built against yesterday's API, and never updated, still behave correctly? Walking through common changes with that question gives a fairly stable table.

Change Effect on existing clients
Add an optional field to a response Usually safe; breaks clients that reject unknown fields
Add an optional request parameter Safe
Remove or rename a response field Breaks every client that reads it
Change a field's type or unit Breaks, often silently
Make a request field required Breaks every client that doesn't send it
Return null where a value was always present Breaks clients that never checked
Add a new value to an enum Breaks clients that treat unknown values as errors
Change the default sort order or page size Breaks clients that relied on the old default

The type change in the invoice example is the worst row, because a string that parses as a number and a number are both accepted by lenient code. The client keeps running and writes wrong data.

The way to ship a change like that is to add first and remove later, sometimes called expand and contract. Add a new field, total_cents: 1999, next to the old total: "19.99", and serve both. Update your own clients to read the new field.

Here are the two old clients, unchanged, reading the original response, the agent's change and the expanded response:

TypeScriptRuns in your browser
// The customer's billing script. res.json() returns `any`, so nothing checks the type.
const scriptAmount = (invoice: any) => `$${parseFloat(invoice.total).toFixed(2)}`;

// The mobile app's decoder, which expects `total` to be a string.
function appScreen(invoice: any): string {
  if (typeof invoice.total !== "string") return `error screen (total is a ${typeof invoice.total})`;
  return `shows ${invoice.total}`;
}

const responses: [string, string][] = [
  ["original", '{"id":"inv_1","total":"19.99"}'],
  ["agent's change", '{"id":"inv_1","total":1999}'],
  ["both fields", '{"id":"inv_1","total":"19.99","total_cents":1999}'],
];

for (const [label, body] of responses) {
  const invoice = JSON.parse(body);
  console.log(`${label.padEnd(15)} script: ${scriptAmount(invoice).padEnd(9)} app: ${appScreen(invoice)}`);
}

The agent's change sends one client wrong numbers and the other to an error screen. The expanded response gives both of them exactly what they had before, while new code reads total_cents.

Mark the old one deprecated in the documentation and tell API customers the date it will be removed. For clients whose versions you control, such as your own mobile app, track how many users are still on each version, and remove the field only when the versions that need it are gone. Your logs can't tell you which fields an outside integration reads, so for those you ask: get confirmation that each integration has moved, or keep the old shape alive under the old API version. Then remove the field, or keep it forever if the cost of keeping it is small.

A flow in two rows. Original, total as the string 19.99, leads by add total_cents to the highlighted Expand, serve total and total_cents, which leads by update own clients to Deprecate, announce a removal date. Deprecate leads down to a diamond, Clients moved? old versions gone, integrations moved. A not yet arrow loops back up to Deprecate; a yes arrow leads left to Contract, remove total, or keep it. A note reads: add first, remove later.
The new field ships beside the old one, and the old one is removed only after the client versions that read it are gone and outside integrations confirm they have moved. Until then, both fields stay.

When a change can't be made additive, give the new shape a new version, such as /v2/invoices, and keep /v1 running with the old shape. Stripe takes this further: its API essay describes pinning each account to the version it first used and translating responses back to that version's shape, so old integrations keep working while the API changes underneath them. Whatever scheme you use, a breaking change always ships with a version number that tells clients they have to opt in.

Bounding every response

The same agent is asked for an activity feed and adds GET /v1/projects/{id}/events, which returns every event for the project. On the development database, a project has 200 events and the response comes back in a few milliseconds.

Your largest customer's project has 4 million events. At around 400 bytes of JSON each, the full response is 1.6 GB. The database reads every row, the server holds all of them in memory while it builds the JSON, and the request runs past whatever timeout sits in front of the server, so the client receives nothing.

A Client box, receives nothing, sends a request to a highlighted Server box, which builds 1.6 GB of JSON from a Database cylinder that reads every row. From the client, a Timeout box, fires while the server is still working, leads to a Retry pill, same request, which sends the request to the server again along an arrow labelled same work again. A note reads: every retry repeats it.
The timeout in front of the server fires while the database and server are still working, so the client receives nothing. Its retry sends the server through all that work again.

The client then retries, and the server does all that work again. An endpoint with no limit works for every account until the day one account grows, and then it becomes a way for a single request to exhaust your server's memory.

Every list endpoint needs a limit the server enforces, with a default and a maximum, and a way to fetch the next page. A common first attempt is an offset: ?limit=50&offset=200000.

It has two problems. The database still has to walk past 200,000 rows to throw them away, so late pages get slower. And if new events arrive while a client is paging, every row shifts down, so the client sees some events twice; deletions make it skip some.

Keyset pagination, often exposed as a cursor, avoids both. Each page remembers the last row it returned, and the next page asks for rows after that one.

SQL
SELECT id, kind, created_at
FROM events
WHERE project_id = $1 AND id < $2
ORDER BY id DESC
LIMIT $3;

The first page, which has no cursor, drops the id < $2 condition. With an index on (project_id, id), the database jumps straight to the right place, so page 10,000 costs about the same as page 1. New rows land at the top and don't shift anything below the cursor. If you sort by a timestamp instead of an ID, add the ID as a tiebreaker, because two rows can share a timestamp.

You can run both kinds of page against the same table. A new event arrives while the client is reading page 1:

SQLRuns on SQLite in your browser
CREATE TABLE events (id INTEGER PRIMARY KEY, project_id TEXT, kind TEXT);
INSERT INTO events (id, project_id, kind) VALUES
  (1, 'p_42', 'task.created'), (2, 'p_42', 'comment.created'), (3, 'p_42', 'task.assigned'),
  (4, 'p_42', 'task.closed'), (5, 'p_42', 'comment.created'), (6, 'p_42', 'task.reopened');

-- Page 1, newest first. The last row it returns is id 4.
SELECT 'page 1' AS page, id, kind FROM events
WHERE project_id = 'p_42' ORDER BY id DESC LIMIT 3;

-- A new event lands between the two requests.
INSERT INTO events (id, project_id, kind) VALUES (7, 'p_42', 'task.created');

-- Page 2 by offset: skip the 3 rows already shown.
SELECT 'page 2, offset' AS page, id, kind FROM events
WHERE project_id = 'p_42' ORDER BY id DESC LIMIT 3 OFFSET 3;

-- Page 2 by cursor: rows older than the last one shown.
SELECT 'page 2, cursor' AS page, id, kind FROM events
WHERE project_id = 'p_42' AND id < 4 ORDER BY id DESC LIMIT 3;
Four columns of event rows, newest first. Page 1 shows events 6, 5 and 4. After event 7 lands, the table reads 7, 6, 5, 4, 3, 2, 1, and an arrow labelled down one place shows event 4 moving from the third position to the fourth. Offset page 2, OFFSET 3, skips three rows and shows events 4, 3 and 2, with event 4 highlighted. Cursor page 2, id less than 4, shows events 3, 2 and 1. Notes read: event 4 shown twice; as if nothing was inserted.
Event 7 lands between the two requests and pushes every row down one place. Skipping three rows by offset lands on event 4 again, while asking for ids below 4 starts at event 3, as if nothing had been inserted.

The offset page shows event 4 a second time, because event 7 pushed every row down one place. The cursor page starts at event 3, as if nothing had been inserted. The client still has to fetch event 7 by starting again from the top, which is what a feed does when it refreshes.

The server hands the cursor to the client as an opaque string, so you can change what's inside it later without breaking anyone.

TypeScript
const DEFAULT_LIMIT = 50;
const MAX_LIMIT = 100;

function parseLimit(raw: unknown): number | null {
  if (raw === undefined) return DEFAULT_LIMIT;
  const n = Number(raw);
  return Number.isInteger(n) && n >= 1 && n <= MAX_LIMIT ? n : null;
}

function encodeCursor(lastId: number): string {
  return Buffer.from(JSON.stringify({ id: lastId })).toString("base64url");
}

function decodeCursor(raw: string): number | null {
  try {
    const parsed = JSON.parse(Buffer.from(raw, "base64url").toString("utf8"));
    return Number.isSafeInteger(parsed?.id) ? parsed.id : null;
  } catch {
    return null;
  }
}

The handler fetches limit + 1 rows. If it gets the extra row, there is another page, and the response carries a cursor built from the last row it returns:

JSON
{
  "data": [{ "id": 88123, "kind": "comment.created", "created_at": "2026-09-14T08:12:44Z" }],
  "next_cursor": "eyJpZCI6ODgxMjN9"
}

When next_cursor is absent, the client has reached the end. A cursor that fails to decode is the client's mistake and gets a 400 response.

The same thinking applies to requests. Cap the size of request bodies, the number of IDs a batch endpoint accepts, and the rate at which one API key can call you. Each of these is part of the contract, so publish them.

Errors callers can act on

An error response has two readers. A program needs to decide what to do next, and a person debugging needs to know what went wrong. If every endpoint invents its own shape, one returning { "error": "bad" }, another { "message": ..., "code": 12 }, and a third a plain-text string, then every client has to special-case every endpoint.

RFC 9457, Problem Details for HTTP APIs, defines one shape, served with the content type application/problem+json:

JSON
{
  "type": "https://api.example.com/problems/invalid-parameter",
  "title": "Invalid query parameter",
  "status": 400,
  "detail": "limit must be an integer from 1 to 100",
  "instance": "/v1/projects/p_42/events"
}

type is a stable identifier a program can switch on. title is a short human summary of that type, and detail explains this particular occurrence. You can add your own fields, such as a request ID.

The status code is the first hint about whether trying again could help, and the endpoint's documented errors settle it. A 400 or 422 means the request itself is wrong, and sending the same bytes again will fail the same way. A 404 usually means the same, but it can be temporary, for example when a record hasn't replicated yet. A 409 says the request conflicts with the current state, so it may succeed once the client has resolved the conflict. A 429 or 503 means try later, ideally after the wait given in a Retry-After header, which holds either a number of seconds or an HTTP date (RFC 9110). A 500 means something broke on the server, and the client should retry only if the operation is safe to repeat.

Five status code pills on the left each point to what the code means for a retry, and the five meanings sit together in one frame headed The first hint. 400 and 422: request is wrong, the same bytes fail the same way. 404: usually wrong, but may be temporary, not replicated yet. 409: conflict, may succeed once resolved. 429 and 503: try later, ideally after Retry-After. 500: server broke, retry only if safe to repeat. An arrow labelled settled by leads from the frame to a highlighted box, Documented errors for this endpoint. A note reads: whether trying again could help.
The status code is the client's first hint about whether sending the request again could help; the endpoint's documented errors settle it.

The error body is also where agents leak internals. A handler like this is common in generated code:

TypeScript
res.status(500).json({ error: err.message, stack: err.stack });

A stack trace tells an outsider your file layout, library versions and sometimes fragments of SQL. Log the details on the server under a request ID and return only the ID.

TypeScript
app.use((err: unknown, req: Request, res: Response, _next: NextFunction) => {
  const requestId = crypto.randomUUID();
  logger.error({ requestId, path: req.path, err }, "unhandled error");
  res.status(500).type("application/problem+json").json({
    type: "about:blank",
    title: "Internal Server Error",
    status: 500,
    request_id: requestId,
  });
});

Putting this in one error handler, and having every endpoint throw typed errors that the handler maps to problem details, is how the shape stays the same across endpoints written by different people and different agents.

Writing the contract down

Everything above works better when the contract exists as a file a machine can read. OpenAPI describes HTTP endpoints, their parameters and their response bodies, using JSON Schema for the shapes. Here is the invoice as the API originally promised it. This fragment sits inside a full OpenAPI document, which also has the top-level openapi, info and paths fields that the generator needs:

YAML
components:
  schemas:
    Invoice:
      type: object
      required: [id, total]
      properties:
        id:
          type: string
        total:
          type: string
          pattern: "^[0-9]+\\.[0-9]{2}$"
          description: Amount in dollars, as a decimal string.

From a file like this you can generate client types, for example with bunx openapi-typescript openapi.yaml -o api.d.ts, and validators for tests. A contract test calls the real endpoint and checks the response against the published schema. Here ./schemas exports invoiceSchema, the Invoice schema above loaded as a plain JSON Schema object:

TypeScript
import { test, expect } from "bun:test";
import Ajv from "ajv";
import { invoiceSchema } from "./schemas";

const validateInvoice = new Ajv().compile(invoiceSchema);

test("GET /v1/invoices/:id matches the published schema", async () => {
  const res = await fetch(`${process.env.API_URL}/v1/invoices/inv_test_1`);
  const body = await res.json();
  validateInvoice(body);
  expect(validateInvoice.errors ?? []).toEqual([]);
});

Run against the agent's change, this test fails with "must be string" on /total. That failure forces the right conversation: either the schema changes, which is a public decision that can be reviewed as such, or the code changes back. A schema diff tool such as oasdiff can compare the old and new OpenAPI files in CI and fail the build on any change that breaks existing clients in a way the document can express, before a person even reads the diff. Promises the schema doesn't describe, such as the order items come back in or the unit of an amount, need tests of their own: a test that creates three events and asserts they come back newest first will catch a changed sort that no schema diff would.

Check your understanding

7 questions on this lesson. Pick an answer to see whether it holds and why.

  1. 1Four changes are proposed for GET /v1/products/{id}, which outside integrations call. Which one can existing clients most likely survive without any change on their side?
    Show the answer

    Answer D. Adding an optional field leaves every field an old client reads exactly as it was, so only clients that reject unknown fields notice. The null change looks harmless, but code that calls a string method on description or checks its length has never had to handle null and now fails on it.

  2. 2A client pages through tasks with offset pagination, two at a time. Between its first and second request, task 2 is deleted. Which task does the client never see?
    SQL
    -- tasks has ids 1 to 6
    SELECT id FROM tasks ORDER BY id LIMIT 2 OFFSET 0;  -- returns 1, 2
    -- task 2 is deleted here
    SELECT id FROM tasks ORDER BY id LIMIT 2 OFFSET 2;
    Show the answer

    Answer B. After the delete, the remaining rows are 1, 3, 4, 5, 6, and skipping two of them lands on 4. Task 3 moved up into the first page's range after the client had already read it. A cursor of WHERE id > 2 would start at 3 whatever was deleted before it.

  3. 3Your client gets this response to a POST /v1/exports. What should it do?
    HTTP
    HTTP/1.1 429 Too Many Requests
    Retry-After: 30
    Content-Type: application/problem+json
    
    {"type":"https://api.example.com/problems/rate-limited","title":"Rate limit exceeded","status":429}
    Show the answer

    Answer A. A 429 says the request was fine but the caller is going too fast, and Retry-After says how long to wait. The 4xx reading is tempting, but a 400 or 422 means the bytes are wrong; a 429 means the timing is. Retrying at once makes the rate problem worse for every caller sharing the limit.

  4. 4A client's POST /v1/transfers gets a 500 with a request ID and no other detail. When is it safe for the client to retry?
    Show the answer

    Answer C. A 500 says something broke on the server, and it may have broken after the transfer was recorded. Repeating a request that is not safe to repeat can then send the money twice. Retrying always is the tempting answer, but the client cannot tell from a 500 alone whether the work was done.

  5. 5An agent added a limit to a list endpoint. What is still wrong with it?
    TypeScript
    const limit = Number(req.query.limit ?? 50);
    const { rows } = await db.query(
      "SELECT id, kind, created_at FROM events WHERE project_id = $1 ORDER BY id DESC LIMIT $2",
      [projectId, limit],
    );
    Show the answer

    Answer A. The server only chooses the limit when the caller says nothing; any caller can still ask for every row, which is the unbounded response the limit was meant to prevent. The server should reject or cap anything above a published maximum. Number("abc") does not throw; it returns NaN, which is a separate bug the same check would catch.

  6. 6A contract test validates every GET /v1/projects/{id}/events response against the published JSON Schema, and a schema diff runs in CI. An agent changes the endpoint to return events oldest first instead of newest first. What catches it?
    Show the answer

    Answer C. The order of items is part of the contract, but the schema describes only shapes and types, and an array sorted the other way has the same shape. So the contract test, the schema diff and the generated types all pass. A promise the schema cannot express needs a test of its own.

  7. 7Version 1 of POST /v1/invites accepted a body of { "email": ... }. An agent added roles and changed the handler to this. What happens to existing clients?
    TypeScript
    const InviteSchema = z.object({
      email: z.string(),
      role: z.enum(["admin", "member"]),
    });
    const body = InviteSchema.parse(await req.json());
    Show the answer

    Answer B. A z.enum field with no .optional() or .default() is required, so a body without role fails to parse. Making a request field required breaks every client that does not send it. Treating the new field as optional with a default of member would have kept old clients working.

You understand it when you can

Drill

While fixing a typo, an agent renamed the user_name field to username in a public API response, and in the same change added a GET /orders endpoint that returns every order in one response. Find which clients break, what the endpoint does for your largest account, and how each change should have shipped.

Topics

API Design
Resources, operations and naming that match the domain and are hard to misuse.
Error Contracts
Consistent error shapes and codes that tell callers what went wrong and whether a retry could help.
Versioning and Compatibility
Adding without breaking, deprecating deliberately, and knowing who depends on what.
Pagination, Filtering and Limits
Bounding every response and every request so no caller can ask for everything at once.
Schemas as Contracts
Machine-readable definitions, such as OpenAPI, JSON Schema or protocol buffers, that validate data and generate code.

Further reading

Start here

  • How To Design A Good API and Why it Matters. Joshua Bloch, 2007. 60-minute talk.

    Bloch's rules for APIs that are easy to use and hard to misuse: 'when in doubt leave it out', public APIs are forever, and names and failure behavior are part of the contract. These apply directly to REST and RPC design.

Short reads

Watch

  • Practical API Design • Ronnie Mitra • GOTO 2019. Ronnie Mitra, 2019. 42-minute talk.

    Mitra walks through how naming and interface shape decisions affect the developers who call a web API.

  • API Evolution without Versioning. Brandon Byars, 2023. 49-minute talk.

    Byars covers the ways an API can change without breaking existing clients, the trade-off between elegance and stability, and when a versioned break is justified. This is the missing thinking behind renaming user_name to username.

Books

  • API Design Patterns. JJ Geewax, 2021.

    Distilled from Google's API design guidance: resource naming, standard methods, pagination with page tokens, field masks and versioning, each with the failure it prevents.

  • The Design of Web APIs. Arnaud Lauret, 2025, 2nd edition.

    Takes a REST API from requirements to an OpenAPI description, with chapters on error design, handling non-backward-compatible changes and versioning, and standardizing design decisions.

  • Principles of Web API Design: Delivering Value with APIs and Microservices. James Higginbotham, 2021.

    An outside-in method for mapping domain operations to resources and choosing among REST, gRPC, GraphQL and async styles, including how to document the contract before building it.

Primary sources

  • RFC 9457: Problem Details for HTTP APIs. RFC.

    The IETF standard for one consistent machine-readable error body (type, title, status, detail, instance). It answers the problem of error shapes that change from endpoint to endpoint.

  • Google API Improvement Proposals (AIPs). Reference.

    Google's public API design rules, with individual AIPs on pagination, errors, and backwards compatibility that define what counts as a breaking change.