Versioning

Versioning is a way for clients to indicate what features they support.

Strategies

As with all interesting engineering problems, approaches to versioning have different tradeoffs.

Root Folder Versioning

A common approach is to prefix the API URL with a version folder: /api/v1/<rest>.

Advantages:

• Quick to set up.
• Easily navigable with a browser.
• Third party clients are not able to opt in to only part of the new functionality.

Disadvantages:

• You lose Search Engine ranking every time you bump the version number.
• Any URLs you use as identifiers will become invalidated when you bump the version.
• First party clients are not able to gradually migrate.

Version Header

A less common approach is to use a header like X-API-Version: 1 in API requests. There are two approaches within this strategy that have different tradeoffs.

Don't Allow Requests Without Header

Advantages:

• Third party clients are not able to opt in to only part of the new functionality.
• Clients are unable to accidentally depend on a changing version number.
• URLs can be used as identifiers.

Disadvantages:

• No Search Engine indexing.
• Not usable through a browser without an API viewer.
• First party clients are not able to gradually migrate.

Default to Latest Version

Advantages:

• Third party clients are not able to opt in to only part of the new functionality.
• Somewhat navigable with a browser.
• URLs can be used as identifiers.
• Search Engine always indexes latest version.

Disadvantages:

• Will not result in backwards compatibility in practice as clients will (accidentally) use the latest version and will break when that changes.
• First party clients are not able to gradually migrate.

Default to v1

Advantages:

• Third party clients are not able to opt in to only part of the new functionality.
• Limited navigability with a browser.
• URLs can be used as identifiers.

Disadvantages:

• Makes it impossible to remove support for v1.
• First party clients are not able to gradually migrate.
• Search Engine always indexes old version.

Authentication Token Versioning

An uncommon approach is to couple the version to the authentication credentials of the client.

Advantages:

• Easily navigable with a browser.
• Third party clients are not able to opt in to only part of the new functionality.
• URLs can be used as identifiers.

Disadvantages:

• No Search Engine indexing.
• First party clients are not able to gradually migrate.
• Cannot be used for public APIs.
• Makes it harder to cache static content.

Content Negotiation

By leveraging Content Negotiation and defining your own Media-Types clients can indicate which versions of individual responses they can handle. This means that as long as there is any overlap between the versions the server and the client supports they can communicate. Using this technique you can also present interactive users with a web fallback if there is no overlap.

Advantages:

• Clients can slowly migrate to newer versions.
• Can continue to give limited functionality to ancient clients through a web fallback.
• Clients can support multiple server versions.
• URLs can be used as identifiers.

Disadvantages:

• Hard to explore without an API viewer like media-types-serialization provides.