Versioning and compatibility

Topics in this section
2 cards

What breaks clients

Once an API is public, clients you've never met depend on its exact shape. A change is backwards compatible if every existing client keeps working. Usually safe: adding a new endpoint, a new optional request field, a new response field.

Breaking: removing or renaming a field, changing its type (an id from number to string), making an optional field required, changing a status code or the meaning of a value, changing defaults (page size, sort order). Adding a value to an enum is a grey zone: clients with a strict switch over the old values can crash, so document from day one that enums may grow and clients must handle unknown values.

The matching client rule is to ignore unknown fields, so the server can add them freely.

In real life

A field renamed from total to total_amount: every client reading total now gets nothing, and none of them changed a line of code.

Check yourself

Which changes to a public API are backwards compatible? (Choose two.)

Select 2, then check.

Versions and deprecation

When a breaking change is unavoidable, ship it as a new version and keep the old one running for a stated period. Common styles: a path prefix, /v1/orders → /v2/orders (visible, easy to route, the most common); a header, such as Stripe's Stripe-Version: 2024-06-20, where each account is pinned to the version it started with; or a media type in Accept, rarer in practice.

Whatever the style, the process matters more: announce the change, give a date, mark old endpoints with the Deprecation and Sunset headers, measure who still calls them, and contact those clients before switching off.

In real life

Stripe pins each account to an API version by date and lets it upgrade when ready; GitHub's REST API uses a dated X-GitHub-Api-Version header.

In code: HTTP
GET /v1/orders/42
→ 200 OK
Deprecation: @1767225600          # when it was deprecated (a Unix time)
Sunset: Fri, 01 Oct 2027 00:00:00 GMT
Link: </v2/orders/42>; rel="successor-version"
  • The Sunset header is RFC 8594; the Deprecation header is RFC 9745.
  • Path versioning is the easiest to see in logs and to route at a gateway.
Check yourself

You must remove a field that some clients still use. Which steps are part of a responsible change? (Choose three.)

Select 3, then check.