Versioning on media types

Another approach to versioning is using MIME types to include the API version. In short, API producers register these MIME types on their backend and then the consumers need to include accept and content-type headers.

The following code lets you use an additional header:

GET https://<HOST>/orders/1325 HTTP/1.1
Accept: application/json
Version: 1

GET https://<HOST>/orders/1325 HTTP/1.1
Accept: application/json
Version: 2

GET https://<HOST>/orders/1325 HTTP/1.1
Accept: application/json
Version: 3

The following code lets you use an additional field in the accept/content-type header:

GET https://<HOST>/orders/1325 HTTP/1.1
Accept: application/json; version=1

GET https://<HOST>/orders/1325 HTTP/1.1
Accept: application/json; version=2

GET https://<HOST>/orders/1325 HTTP/1.1
Accept: application/json; version=3

The following code lets you use a Media type:

GET https://<HOST>/orders/1325 HTTP/1.1
Accept: application/vnd.<host>.orders.v1+json

GET https://<HOST>/orders/1325 HTTP/1.1
Accept: application/vnd.<host>.orders.v2+json

GET https://<HOST>/orders/1325 HTTP/1.1
Accept: application/vnd.<host>.orders.v3+json