.png){kind=small}
.png){kind=small}
Do you know what API versioning is and which are the best practices regarding security, governance and developer experience? In this article we will bring the definition of this concept, types of versioning and best practices.
It's the natural cycle, everything changes, including APIs. Exemplary and highly used APIs also undergo changes, it's inevitable. However, that doesn't mean it is cool, because changes generate impacts, costs, and if the versioning strategy is not done well, it can impact the business, causing the loss of customers or partners. Therefore, it is extremely important to understand what API versioning is, which are the types, how to structure a strategy and the best practices in everything that involves changes in APIs.
It is the process of implementing changes to a given API. When we make changes that modify the structure of that API, we have to version it. We use semantic versioning for version control.
According to good practices: major standard (eg v1) on display for consumers and minor standard (eg v1.2) for internal changes that do not cause breach of contract.
APIs are consumed from a contract (swagger), defined by OpenAPI Specification. Therefore, any changes applied to this contract can break the integrations that are consuming the API. As a result, when we alter its structure, we are breaking that contract (and possibly the integrations).
The concept of what is or isn’t a breach of contract varies from organization to organization. For some companies, the contract is only broken when new mandatory fields are inserted or when some authentication/authorization flow is inserted.
Other companies, however, consider that the breach of contract doesn’t depend on the obligation. So, if a new parameter is inserted in the body of a POST request, even though it’s not mandatory, the contract has been modified, thus generating the break (even if not necessarily in the integration).
In most cases, we use external versioning (major standard) when:
For internal versioning (minor standard):
The first step in ensuring a proper versioning strategy is knowing when to version. Besides defining this concept in the organization, it’s also necessary to define which type of versioning will be used.
This is the most common type of API versioning. The version is informed in the URI (Uniform Resource Identifier) of the request. Very easy to configure and simple to understand.
In this scenario, versioning is done via header, leaving the URI cleaner. It’s widely used in content negotiation scenarios, where we can work with single representation per resource.
As with the Accept Header, in this type of versioning we also work with the version via header, but in a customized way. In the backend, a customized way of working with the API version is developed. The usage scenarios also apply to Accept Header. The difference is that this type is customized, generating more flexibility.
Like versioning via URI path, the Query Parameter is also easy to setup, but can be a bit more difficult to work with in version routing.
Versioning through subdomain usually involves different types of services (backend) where we can have different versions for different services. For example, v1 for a webservice, and v2 for a microservice.
Now that you know what API versioning is and its types, we can talk about versioning strategy. After all, you don’t want just to flip the switch from Vx to Vy, right?
The first step of the versioning strategy is to define if it really needs to version the API (just kidding… or not!). After understanding that versioning is inevitable, the next step is to identify the consumers that will be impacted by the change. Are you aware of all the developers/applications that use your APIs, right?
After identifying these consumers, the second step is to work on communication. Will it be done via email? Via developer portal? How and through which channels will it happen?
The third step is to determine the deadline for adequacy. This deadline will depend on several factors such as the type of API, the type and number of consumers, the type of change that is being carried out… Some companies set a deadline of 6 months, others of 2 years… It really depends!
The fourth step is to reflect on possible problems that can happen when versioning this API. The best way to work on versioning is when there is compatibility with previous versions. If a problem happens, the consumer will be able to easily go back to the previous version without much impact.
And the fifth and final step, which is actually more of a recommendation, is: HAVE A MAXIMUM OF 2 API VERSIONS LIVE!
In theory it's usually easy, but in practice it doesn't always work as we'd like. However, always keep in mind that the fewer API versions available, the lesser the possibility of negative impact on its governance and, consequently, on its security. It's worth noting that governance-related flaws are among the most common vulnerabilities in APIs according to OWASP Top 10 API Security.
It's important to highlight that in technology there is hardly a “silver bullet”, and API versioning is no different. There is no best type nor best strategy. It will always depend on the organization's internal policies, use case, types of consumer, API type, etc. Even though there is no “silver bullet”, there are several market practices that we use and that you could get to know.
