How to handle API updates and versioning
| Compatibility policy |
| Backwards compatibility |
| Structured representations (application/json) |
| API versioning |
Content type negotiation
The Accept header may include the v parameter to specify the API version requested; see “Versioning” below. |
| Versioning |
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 |
| Versioning |
Compatibility
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 |