Versioning - Revision history

Thexa4 at 02:15, 19 January 2021

2021-01-19T02:15:10Z

← Older revision		Revision as of 19:15, 18 January 2021
Line 78:		Line 78:
	Disadvantages:		Disadvantages:
	* Hard to explore without an API viewer like [[Media-Types Serialization]] provides.		* Hard to explore without an API viewer like [[Media-Types Serialization]] provides.


			[[Category: Terminology]]

Thexa4: /* Version Header */

2021-01-19T01:59:47Z

Version Header

← Older revision		Revision as of 18:59, 18 January 2021
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 ====

Thexa4 at 16:41, 15 January 2021

2021-01-15T16:41:20Z

← Older revision		Revision as of 09:41, 15 January 2021
Line 77:		Line 77:

	Disadvantages:		Disadvantages:
	* Hard to explore without an API viewer like [[~~media~~-~~types-serialization~~]] provides.		* Hard to explore without an API viewer like [[Media-Types Serialization]] provides.

Thexa4 at 17:14, 14 January 2021

2021-01-14T17:14:47Z

← Older revision		Revision as of 10:14, 14 January 2021
Line 5:		Line 5:

	=== Root Folder Versioning ===		=== Root Folder Versioning ===
	A common approach is to prefix the API [[URL]] with a version folder: `/api/v1/<rest>`.		A common approach is to prefix the API [[URL]] with a version folder: <code>/api/v1/<rest></code>.

	Advantages:		Advantages:
Line 18:		Line 18:

	=== Version Header ===		=== 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.		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.

	==== Don't Allow Requests Without Header ====		==== Don't Allow Requests Without Header ====

Thexa4: Created page with "Versioning is a way for clients to indicate what features they support. == Strategies == As with all interesting engineering problems, approaches to versioning have different..."

2021-01-14T15:53:52Z

Created page with "Versioning is a way for clients to indicate what features they support. == Strategies == As with all interesting engineering problems, approaches to versioning have different..."

New page

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 [[URL | 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.
* [[URL | 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.
* [[URL | 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.
* [[URL | 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.
* [[URL | 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.
* [[URL | URLs]] can be used as identifiers.

Disadvantages:
* Hard to explore without an API viewer like [[media-types-serialization]] provides.