2.1 KiB
Changes and Versioning
The fundamental principle is that you can’t break existing clients, because you don’t know what they implement, and you don’t control them. In doing so, you need to turn a backwards-incompatible change into a compatible one.
Any change to an API MUST NOT break existing clients.
Any change to:
- resource identifier (resource name / URI) including its query parameters and their semantics
- resource metadata (e.g. HTTP headers)
- actions the resource affords (e.g. available HTTP Methods)
- relations with other resources (e.g Links)
- representation format (e.g. HTTP request and response bodies)
MUST follow the Rules for Extending.
No URI Versioning
A change SHALL NOT affect existing resource identifiers (name / URI).
Example
Adding a new action to existing resource with identifier /greeting doesn't change its identifier to /v2/greeting.
Backward-incompatible Change
A change to resource identifier, resource metadata, resource actions and resource relations, that can't follow the Rules for Extending MUST result into a new resource variant. Existing resource variant MUST be preserved.
A change to representation format SHOULD NOT result into a new resource variant.
Representation Format Change
A representation format is the serialization format (media type) used in request and response bodies and typically it represents a resource or its part, possibly with additional hypermedia controls.
If the change can't follow the Rules for Extending the representation format media type MUST be changed. If the media type has been changed the previous media type MUST be available via Content Negotiation.
Example
Media type before a breaking change:
application/vnd.example.resource+json; version=2
Media type after a breaking change:
application/vnd.example.resource+json; version=3
API Description Versioning
TODO