A single change will carry this whole article. Suppose your company runs a customer API. One endpoint returns a customer record, and it has a single field called name holding “Priya Raghunathan”. Marketing wants personalised emails that start with “Dear Priya”, which needs the first name separately. So the plan is to split name into first_name and last_name.
Fifteen internal and partner systems read this endpoint. You do not control most of their release dates. How do you make the change without breaking any of them? Let us go step by step.
Step 0: sort changes into safe and unsafe
The first skill is classification. Some changes are additive and normally safe: a new optional field in a response, a new endpoint, a new optional request parameter. Clients written sensibly ignore fields they do not recognise. Other changes are breaking: removing or renaming a field, changing its type (a number becomes a string), changing the meaning of a value, making an optional input mandatory, tightening validation, or changing an error format that clients parse.
Our split involves two additions and one removal. Additions are fine. The removal of name is the dangerous part, and it must wait.
A caveat on “safe”: a client that rejects unknown fields, or a strictly typed generated client, can break even on additions. This is why API designers often publish the rule that consumers must tolerate unknown fields. Tolerant readers make evolution possible; strict ones make you freeze the API.
Step 1: add the new fields, keep the old
The response now returns name, first_name and last_name, all populated. Nothing existing changes. On the write side, clients may send the old name or the new pair. If they send only name, the server splits it on a best-effort basis; if they send the pair, the server builds name by joining them. This duplication is deliberate and temporary.
Here the real-world difficulty surfaces. Splitting names automatically is unreliable. Many people have a single name, some communities place the family name first, initials are common in South India, and “Priya Raghunathan” is easy while “Anbu Selvan K” is not. So the server rule needs to be explicit and documented, and the new fields should be allowed to be empty for legacy records, with the team deciding what the email system does in that case. This is a data problem hiding inside an API problem, and it is common.
Step 2: tell people, in several ways
Mark name as deprecated in the API documentation and the machine-readable description (an OpenAPI specification has a deprecated flag for exactly this). Announce it in the changelog and by email to the owners of known consumers. Standards exist to signal it in responses: the Sunset header, defined in RFC 8594, carries the date after which a resource is expected to stop working, and a Deprecation header has also been standardised as an RFC more recently. Do not rely on headers alone. Humans notice emails; most client code never reads headers.
Pick a deprecation window you can defend. For internal consumers, a quarter may be plenty. For external partners with their own release cycles, six to twelve months is common, and regulated partners may need longer. There is no universal number.
Step 3: measure who still uses the old field
This is the step many teams skip, and it is what makes removal safe. Record, per consumer, who is still sending the old input or depends on the old output. Reading is harder to detect than writing, since the server cannot see which response fields a client uses, but you can approximate it: log requests by API key or client identifier, and ask consumers directly. For writes, it is easy: count how many requests supply only name.
Suppose that after three months you find thirteen of fifteen consumers have migrated. The two remaining are a partner’s billing system and an old internal reporting job. Now you have specific people to talk to, rather than a vague worry.
Step 4: remove only when it is cheap to do so, or version
There are now two honest choices. If the last consumers migrate, you can remove name at the announced date. If one cannot, you have to decide whether to extend the window, or to keep name forever. Keeping a redundant field costs almost nothing; breaking a partner’s billing costs a lot. Be willing to leave it.
Versioning enters when changes are bigger than a field: a new resource model, a different auth scheme, changed semantics. You then release a new version, whether in the path, as a version segment, in a header, or via the content type, and run both for a while. The mechanism matters less than the discipline. Every version you keep alive costs testing, documentation and support, so each one should have an end date, and you should prefer additive evolution within a version as much as possible, so that new versions are rare.
What the example shows
Look back at the shape of what we did: expand (add new beside old), migrate (consumers move at their own pace), contract (remove old once safe). Database engineers know the same rhythm as expand-and-contract. It turns one risky, simultaneous change into several small, reversible ones, and it fits the reality that you control your server but not your clients’ calendars.
A few habits make all of this easier. Use contract tests so a provider build fails if it breaks something a consumer relies on. Keep error formats stable and documented. Never reuse a field name with a new meaning; add a new field instead. Keep a changelog. And treat the API as a product with users, since in practice it is.
Figures and names in the examples are illustrative.
Leave a Reply