Changing an API without breaking callers

Interviewers ask: "Your API is live. You must rename a field. What do you do?" They test whether you know that you cannot update every caller at once.

A weak answer changes the field and says "the clients will update". A strong answer adds the new field beside the old one and announces an end date. It removes the old one only when call counts show that almost nobody uses it.

Think about changing your phone number. You keep the old number working for some months and tell people the new one.

A caller is a program that uses your API: your own app, or a partner system. You cannot update every caller yourself. A phone app stays on the old version until its user updates it. A change is breaking if a caller that worked before now fails. A change is backward compatible if old callers keep working.

Safe changes (backward compatible):

• Add a new field to an answer.
• Add an optional input, with a default value.
• Add a new path.

These are safe only if callers ignore fields they do not know. Tell callers this rule from the start.

Breaking changes:

• Remove or rename a field.
• Change the type or meaning of a field, for example from rupees to paise (100 paise = 1 rupee).
• Make an optional input required.
• Change a path, a method or a status code.
• Send a new value where callers expect a fixed list, such as a new order status.

A schema is the agreed shape of the data: the field names and their types. To change a schema safely, add the new field beside the old one and return both. Move the callers over. Remove the old field last. Never reuse an old name for a new meaning. Add a new name.

A version is a name for one shape of the API, such as /v1/orders and /v2/orders. Use a new version only when adding cannot do the change. Put the version in the path, because it is the easiest place to see and test. Version the whole API, not each field. Each live version is more code to run and test.

Deprecation means you announce that something will be removed, and when.

1. Announce it with a date.
2. Send two headers on every answer. Deprecation says it is deprecated (RFC 9745). Sunset says the date it stops (RFC 8594).
3. Count the calls that still use it, for each app version.
4. Remove it when the date has passed and the count is low. A removed path then answers 410 Gone, which means gone for good.

GET /orders/42 returns {"id": 42, "total": 250}. We want the name amount.

Assumptions: 100,000 users. 50% have updated the app after 30 days, and 80% after 90 days.

Rename at once. On day 0 every old app breaks. Even on day 30, 100,000 x 50% = 50,000 users still run the old app. Each reads total, finds nothing, and sees an empty or broken screen. This answers the predict box.

Add beside, then remove.

1. Day 0: return {"id": 42, "total": 250, "amount": 250}. The new app reads amount. Old apps still work.
2. Announce on 1 Jan 2027, with these headers. The Deprecation value is that date in seconds since 1 Jan 1970. The Sunset date, 1 April 2027, is 31 + 28 + 31 = 90 days after it.

Deprecation: @1798761600
Sunset: Thu, 01 Apr 2027 00:00:00 GMT

3. Day 90: 100,000 x (100% - 80%) = 20,000 users are still on the old app. Assumption: we remove only when under 1% (1,000 users) remain. 20,000 is more than 1,000, so we do not remove total. We move the date or ask those users to update, then count again.

• Adding beside the old field solves broken callers. It costs a bigger answer and a longer time with two names. I would change to a new version when adding cannot do the change.
• A new version solves big changes. It costs two code paths to run and test. I would not use versions when I own the only caller, because both sides can deploy together.

"Adding a field is always safe." Not if a strict caller fails on a field it does not know.

"Every change needs a new version." Most changes can be additions. Each extra version is more work.

"On the sunset date, I delete the old field." First check the count. In the example, 20,000 users still called on day 90.

1. Name three safe changes and three breaking changes.
2. There are 250,000 users. After 60 days, 70% have updated. You remove the old field when under 1% remain. How many users are on the old app, and can you remove it?
3. A partner sends phone as an optional input. You want it required. What happens, and what do you do?