API design you will not have to version twice

Internal code can be refactored freely because you can see every caller. An API's callers are other people's systems, changed on their schedule, and some of them will not be updated for years. That single asymmetry is what makes API design a different activity from ordinary interface design.

What actually counts as a breaking change

The list is longer than most teams assume, and the surprises are at the bottom.

Pagination: offsets break under writes

Offset pagination is easy to implement and quietly wrong on any dataset that changes while being read. A record inserted between page requests shifts everything down, so one item is skipped; a deletion causes one to repeat.

Offset — page 1 reads rows 1-20. A new row is inserted at the top.
Page 2 reads rows 21-40, but what was row 20 is now row 21: the
client never sees it. On a sync job, that record silently never
arrives, and nothing reports an error.

Cursor — the client sends back an opaque marker for where it stopped.

  GET /orders?limit=20
  { "data": [...], "next_cursor": "eyJpZCI6IjAxSjIifQ" }

  GET /orders?limit=20&cursor=eyJpZCI6IjAxSjIifQ

The cursor encodes the sort key of the last row, so the next page
resumes from a position rather than a count. Inserts and deletes
elsewhere in the set do not shift it.

Requirements: a stable total ordering (a unique tiebreaker after
your sort column), and an opaque cursor — clients must not parse it,
or its format becomes part of your contract.

Offset pagination remains fine for a static reference list or a human browsing a small admin table. It is not fine for anything a machine reads to stay in sync, which is most API traffic.

Errors a client can act on without parsing prose

An error is an API response like any other and deserves the same design attention. It needs a machine-readable code, enough detail to fix the request, and nothing that leaks internals.

{
  "error": {
    "code": "validation_failed",
    "message": "The request contained invalid fields.",
    "details": [
      { "field": "email", "code": "invalid_format",
        "message": "Must be a valid email address." },
      { "field": "quantity", "code": "out_of_range",
        "message": "Must be between 1 and 100." }
    ],
    "request_id": "req_01J2X8Q"
  }
}

• A stable code the client branches on — never the message, which you will want to reword
• Per-field detail for validation, so a form can attach errors without guessing
• A request identifier echoed in your logs, which turns a support conversation into a lookup
• Correct status codes — 400 for a malformed request, 401 unauthenticated, 403 unauthorised, 404 absent, 409 conflict, 422 semantically invalid, 429 rate limited
• No stack traces, SQL or internal hostnames, which are both an information leak and useless to the caller

Idempotency keys, for every unsafe operation

Networks fail after the server has acted but before the response arrives. The client cannot distinguish that from a request that never landed, so it retries — and without idempotency the retry creates a second order, or a second charge.

POST /payments
Idempotency-Key: 7f3c1a90-5c2e-4c15-9f0a-2b7d8e5f1a44

Server behaviour:
  1. Look up the key. If present, return the stored response
     verbatim — same status, same body. Do not re-execute.
  2. If absent, execute, then store the key with its response
     before replying.
  3. Scope keys per caller, and expire them after 24 hours.
  4. If the same key arrives with a DIFFERENT body, return 422.
     That is a client bug, and silently honouring either version
     hides it.

GET, PUT and DELETE are idempotent by definition and need no key.
POST and PATCH do.

Version, but design so you rarely need to

Versioning is a cost, not a feature: every live version is code you maintain and test. The goal is an API that absorbs most change additively, with versioning reserved for the changes that genuinely cannot be.

• Add fields rather than repurposing existing ones; an unused field is cheaper than a changed meaning
• Return objects rather than bare values, so there is somewhere to add later — { "count": 12 } not 12
• Treat every enum as open from the first release
• Never remove a field in place: deprecate, announce, measure real usage, then remove in a version
• Keep at most two live versions, with a published end date for the older one

Before the first external caller

1. 01Write a client against it yourself, in a different language, without reading the source.
2. 02Confirm every list endpoint paginates by cursor and every unsafe endpoint accepts an idempotency key.
3. 03Check that no response leaks another tenant's data given a guessed identifier — the most common real vulnerability in an API.
4. 04Rate-limit per caller, and return the limit, remaining count and reset time in headers.
5. 05Publish a machine-readable schema, generated from the implementation rather than maintained beside it.

The last point matters more than it sounds. Hand-maintained documentation diverges from the implementation within a quarter, and an API whose documentation is wrong is worse than one with none — callers trust it, build against it, and discover the discrepancy in production.