API Versioning
As of now, this versioning strategy has been decided, but not yet implemented in the Bits API. The current path based v1 version is the only version available.
For your information as a client however, this document outlines how versioning will work when v2, and above, is released.
In order to ensure there are no breaking changes to live APIs, Bits leverages API versioning. This allows us to introduce new features and improvements without breaking existing integrations. In this chapter we'll go over how versioning works at Bits and how you as an API client should leverage it.
Media type versioning
The Bits API leverages media type (aka MIME type) versioning. This means that the version of the API is determined by the Accept header in the request, not the URL path.
The Accept header should be set to the media type of the version of the API you want to use.
When an endpoint implements a breaking change (in the request and/or response), a new version of the API is created, which is represented by a new media type. Old media types are still supported, but they will not receive new features or bug fixes.
It's important to note that because we've chosen media type versioning, the URL path will not contain the version number. Instead API endpoints will be versioned independently via the media type.
Meaning one endpoint can be on version 1.0, while another endpoint can be on version 4.0.
Semantic versioning
The Bits media type versioning follows semantic versioning (opens in a new tab). This means that the version number is composed of two parts: major.minor (no patch).
Vendor specific media type
Bits follows the established standard for vendor specific media types as defined in RFC 6838 (opens in a new tab). The media type for the Bits API is application/vnd.bits.v1+json.
Behaviour
If the requested version is not supported, the API will return a 415 Unsupported Media Type response. If the requested version is supported, the API will return a 200 OK response,
with the requested entity in the response body.
Sunset policy
When a new version of the API is released, the previous version will be supported for a minimum of 3 months. After this period, the previous version will be deprecated and eventually sunset. All new API releases will be clearly communicated to Bits clients well in advance, to ensure a smooth transition.
Our 2 cents
Why media type versioning over URL path versioning?
- Dogfooding: We aim to dogfood our own APIs as much as possible, and media type versioning makes it easier for us to move fast (iterate quickly on new APIs) without affecting existing clients.
- Improved Flexibility: It allows clients to request specific versions of resources without relying on the server's URL structure, offering greater flexibility in API evolution.
- Better Cacheability: By abstracting versioning away from the URL, caching mechanisms can cache responses more effectively, as the same URL can serve multiple versions based on the
Acceptheader. - Cleaner URLs: Media type versioning keeps URLs clean and concise, without cluttering them with version numbers.