Our Approach to API Versioning
Beginning with API version 1.2. we are also introducing API versioning in order to guarantee a stable API consumption with legacy features and also being able to introduce new features at the same time.
Having an exposed API is always a balance between providing a stable, non-changing API and on the other side developing a better product.
- Providing a stable, non-changing API means:
- on INTERFACE, on either side request and response, the interface should not change.
- on RESULTS, so the same request should return the same results (unless the data has changed).
- on TIME, all API versions should be accessible at least for one whole year.
By providing a non-changing API running code from our customers will be resilient and reliable.
- Developing a better product means:
- We have to be able to fix errors in the code.
- We have to be able to modify the default API version.
- We have to be able to delete legacy versions.
- We have to incorporate new sources of data.
- We have to develop new features.
Default version and versioning specification
The requested API version should be specified in the requests by using the “Accept” header.
So for example when using the header (“Accept”: “application/json;version=1.0” ) the API version 1.0 will be accessed.
If the request doesn’t have an API version specified it will be using the default version.
Wrong version response
If you try to use a non existing API version you will get a response like the following.
“detail”: “Invalid version in \”Accept\” header.”
Notifications for upcoming changes
In order for customers to have sufficient time to update their request before a breaking change is introduced, we will notify customers about
- depreciating API versions at least 3 months in advance
- new default API versions at least 1 month in advance
- new API versions at least 1 week in advance.
For versioning we are using semantic versioning that can be condensed in this:
Given a version number in the format MAJOR.MINOR.PATCH the:
- MAJOR version is being updated when we make incompatible API changes
- MINOR version is being updated when we add functionality in a backwards compatible manner
- PATCH version is being updated when we make backwards compatible bug fixes.
For next API versions:
|SYSTEM VERSION||MAJOR||MINOR||PATCH||API VERSION|
Understand that only MAJOR and MINOR are exposed to customers, PATCHES will be kept in-house. The reason why is because these patch versions can vary a lot in the first weeks of development and they are non breaking changes and solve specific issues so customers will always receive the most stable PATCH version.
We apply the API versioning like following:
- We are changing MAJOR versions when the API is backwards incompatible in INTERFACE.
- We are changing MINOR versions when the API is changing RESULTS
- We are changing PATCH versions anytime we find something that should be fixed.
That means that when we are changing how the request is done or the response is serialized, even how we internally search, we are changing the MAJOR version.
When we incorporate new sanctions lists we are upgrading the MINOR version but all the interface remains unchanged.
So for example a customer can request both versions 1.0 and 1.2 without changing their code base, understanding that the results will vary because there is a bigger pool of data in the second.
Three Major versions strategy
We will be having a Three MAJOR versions strategy:
- a LEGACY version
- a DEFAULT version
- an INCOMING version