The API you cannot take back

You ship an endpoint that returns a customer:

{ "id": 42, "name": "Priya", "phone": "9876543210" }

Six months later three mobile apps, a partner integration and two internal services depend on it. You now want to split name into first and last.

You cannot. Not because the code is hard, but because an app on somebody's phone from last March still expects name, and you cannot upgrade a phone you do not own.

The rule

Everything you publish is a promise, and you find out who relied on it by breaking it.

Changes that are safe: adding a new field, adding a new endpoint, adding an optional parameter. Anything a caller can ignore.

Changes that are not: removing a field, renaming one, changing a type, making an optional parameter required, changing the meaning of a value while keeping its name. That last one is the cruellest, because nothing fails loudly; the numbers are simply wrong somewhere downstream.

How to change it anyway

1. 1Add the new fields alongside the old ones.
2. 2Keep both for long enough that callers can move, and tell them.
3. 3Watch the logs to see who is still using the old field.
4. 4Remove when the number reaches zero, not when the deadline passes.

Step three is what makes this safe rather than hopeful.

Errors are part of the contract

A caller cannot handle 500 Something went wrong. Tell them what failed, and whether trying again would help:

{ "error": "email_already_registered",
  "message": "That email already has an account.",
  "field": "email" }

A machine-readable code, a sentence a human can show, and the field at fault. The status code says which class of problem: the caller's, yours, or a limit.