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.

Identifier Stability (No URI Versioning)

A change MUST NOT affect existing resource identifiers (name / URI). Furthermore, a resource identifier MUST NOT contain a semantic version to convey a version of resource or its representation format.

The reason to make a real REST API is to get evolvability … a "v1" is a .... to your API customers, indicating RPC/HTTP (not REST)

Example

Adding a new action to existing resource with identifier /greeting doesn't change its identifier to /v2/greeting (or /greeting-with-new-action etc.).

Backward-incompatible Changes

A change to resource identifier, resource metadata, resource actions and resource relations that can't follow the Rules for ExtendingMUST result into a new resource variant. Existing resource variant MUST be preserved.

A change to representation formatSHOULD NOT result into a new resource variant.

Example

Currently, optional URI Query Parameter first on an existing resource /greeting?first=John&last=Appleseed needs to be made required. Since this change violates the 3rd rule of extending and could break existing clients a new variant of the resource is created with different URI /named-greeting?first=John&last=Appleseed.

Representation Format Changes

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 a 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.

If the media type conveys the version parameter, the version parameter MUST follow Semantic versioning.

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

API Description in the OpenAPI specification format MUST have the version field. The version field MUST follow Semantic versioning:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,

MINOR version when you add functionality in a backwards-compatible manner

PATCH version when you make backwards-compatible bug fixes

The API Description version SHOULD be updated accordingly to API design change.