MEPX
Chapter 9 of 10All chapters
  1. 1What an API is
  2. 2The request
  3. 3The response
  4. 4REST and its alternatives
  5. 5Authentication
  6. 6JSON and data shapes
  7. 7Pagination and filtering
  8. 8Rate limits and retries
  9. 9Versioning and change
  10. 10Calling and debugging APIs

Chapter 9 of 10

Versioning and change

Evolving without breaking callers.

What breaks a client

Removing a field, renaming one, changing a type or making an optional input required. Adding a new optional field is safe, and that asymmetry shapes every decision.

  • Version in the path, such as /v1/, when a breaking change is unavoidable.
  • Deprecate with a date and a header before removing anything.

Documentation

An OpenAPI description generates docs, clients and tests from one source. Documentation kept separately from the code is documentation that will be wrong within a month.