For the Swagger Documentation of supported requests and responses, please visit one of the following pages:
There are 2 supported ways to specify and lock the preferred version. All of them are optional, and omitting all will default to Version 1.
This approach of versioning was inspired by Troy Hunt's relevant article.
curl --request GET 'https://<domain>/<path>' --header 'api-version: 1'
It is not required and version 1 is presumed by default.
This approach allowes the API URL to represent the resource. The Zalando API Guidelines, that are based on the OpenAPI Specification, strongly discourage URL versiong. To keep in accordance with that, we facilitate versioning via Content Headers.
The downside is the complexity of making an api call. It is not possible to access versions simply from the browser.
curl --request GET 'https://<domain>/v1/<path>'
Version parameters in the path are not required and can be omitted. Version 1 is presumed by default.
This approach is more convenient, because by specifying the version parameter, GET requests can be simply inspected in the browser. Mapping URLs to specific versions also makes it easy to share a link in a discussion or documentation.
If the URL path contains version information, it is going to take precedent over the request header information.