Versioning and Evolving an API

An API is a promise to clients the team behind it does not control: mobile apps installed months ago, partners on their own release schedule, scripts nobody remembers writing. Every change is either one those clients survive without noticing or one that breaks them, and most of the cost of evolving an API comes from not knowing which is which before release.

The topic opens on the test for a breaking change, then applies it to five changes on one orders API. The tolerant reader shows the client's half of the bargain, and a comparison weighs the four places a version can go. Two walkthroughs follow: retiring a version with the Deprecation and Sunset headers, and renaming a field with expand and contract. A gotcha shows how a new enum value breaks a client although it only adds, and an exercise plans version 2 of an API.

It builds on resources, methods and status codes from the earlier topics in this subject, and on contracts from the topic on request and response contracts.

By the end you can classify a change as breaking or safe, choose where to put a version, plan a deprecation with published dates, rename a field without breaking a client, and predict when a strict client breaks on an additive change.