Updates and Versioning

How to handle API updates and versioning

Content type negotiation
The Accept header may include the v parameter to specify the API version requested; see “Versioning” below.
Public-friendly APIs
a new (breaking/major) version of a set of public-facing APIS should be an entirely new domain (e.g. v2.my-api.example.com), with entirely segregated infrastructure.
List Pagination
Even though adding pagination support to an existing API is purely additive from API surface perspective, it is a behavior-breaking change
This page provides more detailed explanations for the list of breaking and non-breaking changes given in the Versioning section.
Backwards-compatible (non-breaking) changes
Backwards-incompatible (breaking) changes