Practice: Planning Version 2 of an Orders API

Six changes are wanted; sort the safe from the breaking, rename two fields and plan the sunset of version 1.

Planning an API's evolution means sorting what can ship now from what needs expand and contract or a new version, then planning how the old version retires. Here are six changes the team wants for an orders API on path versioning, where v1 has external clients.

Add an optional giftMessage to POST /orders.
Rename customerName to customer.name.
Rename ship_date to shippedAt.
Change total from a number of pounds to an object with amount in pence and currency.
Add a refunded status.
Remove the fax field, which no client has read in a year.

For each, say whether it ships in v1, ships with expand and contract, or needs v2, then write the headers and dates for retiring v1.

Show a plan

Each change and how it ships
Change	How it ships	Why
Optional giftMessage	In v1 now	An optional request field breaks no one
customerName rename	Expand and contract in v1	Both names can coexist while clients move
ship_date rename	Expand and contract in v1	The same pattern; track who still reads the old name
total as an object	In v2	The type changes; old clients cannot read the new shape
refunded status	In v1, once the enum is documented as open	Warn clients first, or it breaks closed enums
Remove fax	In v1 after confirming in logs	Removing a field nobody reads breaks no one

Retiring v1. Publish the plan with a migration guide for the new total. From the deprecation date, send Deprecation with the date and Link with rel="deprecation" on every v1 response, and Sunset with the removal date at least six months later. Track v1 calls by client and contact the stragglers. After the sunset date, answer 410 Gone with a body pointing to v2.

← → move through sections and cards