API Versioning Playbook

Every successful API eventually needs to change, and every change risks breaking someone you cannot see. Versioning is less about picking a URL style and more about having rules for compatibility, a predictable deprecation path and honest communication. Use this playbook to set those rules before the first breaking change forces the issue.

Learning goals

• Distinguish breaking from non breaking changes
• Choose a versioning strategy that fits your consumers
• Define a deprecation policy with dates and signals
• Measure consumer adoption of new versions

Step-by-step procedure

1. Write down your compatibility rules. Adding optional fields and new endpoints is safe. Removing fields, changing types, tightening validation or altering meaning is breaking.
2. Make clients tolerant: document that consumers must ignore unknown fields, and enforce it in your own SDKs.
3. Choose a strategy. Path versions such as v1 are simple and visible. Header or media type versions keep URLs stable but are harder to debug. Pick one and apply it everywhere.
4. Prefer additive evolution. Introduce a new field, keep the old one, and only cut a new major version when the model truly changes.
5. Publish a deprecation policy, for example twelve months notice for stable endpoints, with a sunset date in the documentation.
6. Signal deprecation in the response using headers, and log which API keys still call deprecated routes.
7. Contact affected consumers directly with migration notes, then again at ninety, thirty and seven days before sunset.
8. Remove the old version only after traffic is near zero or the date passes, and publish the removal notice.

Worked example

An orders API returns a single price field as a number in cents. Finance needs multiple currencies. Changing price to an object would break every client. The team adds a new field called money that holds amount and currency, keeps price populated for the default currency, and marks price as deprecated with a sunset date eleven months away. Logging shows that two partners read price. The team emails them with a code sample, offers a test sandbox, and tracks adoption weekly. After the sunset date, traffic on price reads is zero, and it is removed in the next major version, v2, which also cleans up two older oddities that had been waiting for a break.

Exercises and templates

• Classify five recent API changes as breaking or non breaking and justify each.
• Draft a deprecation policy of one page for your team.
• Add a log query that lists consumers using deprecated fields.

Template:

Deprecation: true
Sunset: Sat, 01 May 2027 00:00:00 GMT
Link: <https://example.com/docs/orders-v2>; rel="deprecation"

Common pitfalls

• Versioning every small change, which multiplies the number of versions you must support.
• Never removing anything, so the old version quietly becomes permanent.
• Changing behaviour without changing the contract, for example altering sort order or default page size.
• Announcing deprecation only in documentation that consumers rarely read; use headers, email and dashboards as well.

Follow-up and continuous improvement

Track metrics for every deprecation: number of consumers affected, percentage migrated, and days to sunset. Share them in a short monthly note. When a consumer is stuck, offer help rather than threats: a migration script or a pairing session often costs less than extending support for a year.

Adapting this to your team

Treat everything above as a starting point rather than a rulebook. Smaller teams can compress the sessions and merge roles, while larger organizations may need written templates, a shared calendar and a named owner for the practice. Begin with one pilot on a real project, collect honest feedback from participants, and adjust the format before you roll it out more widely. Consistency matters more than perfection, so favour a simple routine you will actually repeat.

Key takeaways

• Compatibility rules matter more than the version syntax
• Be conservative in what you change and liberal in what clients accept
• Deprecation needs dates, signals and direct outreach
• Data on usage tells you when it is safe to remove