Versioning: Difference between revisions
No edit summary |
No edit summary |
||
(2 intermediate revisions by the same user not shown) | |||
Line 18: | Line 18: | ||
=== Version Header === | === Version Header === | ||
A less common approach is to use a [[header]] like <code>X-API-Version: 1</code> in API requests. There are two approaches within this strategy that have different tradeoffs. | A less common approach is to use a [[HTTP Header | header]] like <code>X-API-Version: 1</code> in API requests. There are two approaches within this strategy that have different tradeoffs. | ||
==== Don't Allow Requests Without Header ==== | ==== Don't Allow Requests Without Header ==== | ||
Line 77: | Line 77: | ||
Disadvantages: | Disadvantages: | ||
* Hard to explore without an API viewer like [[ | * Hard to explore without an API viewer like [[Media-Types Serialization]] provides. | ||
[[Category: Terminology]] |
Latest revision as of 18:15, 18 January 2021
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.