Skip to main content
Goal: change a request or response shape without breaking a client that has not been updated yet.

​
Know whether you are breaking

Not breaking — ship inside v1:
  • a new endpoint
  • a new optional request field
  • a new response field
  • a new error code on an endpoint that already fails
  • a longer description
Breaking — needs v2:
  • removing or renaming a field
  • making an optional field required
  • narrowing a type, range or enum
  • changing a status code
  • changing a default
  • changing the meaning of an existing field
A new enum value is additive in spirit but not in fact: a client that rejects unknown values will break. Treat adding an enum value as breaking if the contract documents the enum as closed.

​
Ship it

​
Notes

A version bump is not a big-bang cutover. Both versions are served at once; clients migrate on their own schedule.
Do not version by header or media type here. A URL a client can read, log and bookmark is worth more than the elegance of the alternative. The reasoning is in versioning.
The generated spec is your migration guide. Its diff shows exactly which fields appeared, vanished or changed type.
Last modified on October 6, 2026