APIs and API management form critical pieces of an enterprise’s technology landscape. A typical API starts with identification of the need for an API and progresses through various lifecycle stages, including design, implementation, testing, deployment, and ongoing management.
With the evolution of business needs and the enterprise and technology landscape, changes to APIs become inevitable. The only constant is change, and APIs are no exception. Therefore it is important how well enterprises are adapted to change when it occurs—because it is bound to occur.
To better manage changes to APIs, the API management artifacts will need to be versioned just like any other software. Such artifacts which include OpenAPI specifications and the API management platform configurations should be version controlled using a source code repository just as one would version the backend services and consumer software code.
Look, we're changing
Changes to API specifications could be due to introduction of new features, changes in business models, data formats, third-party integrations, or deprecation of older versions. This evolution is a story that needs to be told, and not kept under wraps. It is critical to notify the ecosystem that you are changing. The different stakeholders of the API ecosystem includes the API providers, the API platform owners, developers of the backend services, and API consumers.
Versioning OpenAPI specifications
The changes could be impacting (breaking the functioning of any of the stakeholders) or non-impacting (non-breaking) depending on a number of factors.
- Typical breaking changes involve change to data format, inclusion of a new mandatory field, or an optional field becoming mandatory. New privacy regulations or security flaws will most likely result in breaking changes to any or all of the stakeholders.
- Non-breaking changes usually include new functionality being added as a completely new path in the API. Introduction of new non-mandatory fields, while usually might be considered non-breaking from a contract standpoint, could result in a breaking change in API consumers who might not be tolerant to any change in the API specification.
Changes to the APIs should be tracked via the version of the OpenAPI specification. It is good practice to follow semantic versioning to ensure version standardization. A version takes the form of X.Y.Z; refer to Figure 1 to understand how versions are incremented as follows (see Figure 1):
- X major version: Major releases include incompatible API changes which will break consumers, e.g., 1.1.0 to 2.0.0.
- Y minor version: Minor changes or new features without impact on consumers, e.g., 1.0.0 to 1.1.0.
- Z patch version: Bug fixes or patches in which you make backward-compatible changes that don't impact the consumers, e.g., 1.0.0 to 1.0.1.
Impact on stakeholders
Each stakeholder will need to ensure they understand what the changes are, what it means to them, and how they can benefit from them.
As API providers
- Consider API versioning as an opportunity to offer new functionality, and retire APIs which are no longer needed.
- Plan for coexistence of current and previous version(s).
- Have a clear plan for sunsetting of old versions.
- Tread carefully with any and every new change because a new optional field might end up being a breaking change if a consumer is tightly coupled to the API spec and cannot tolerate any variations.
- Ensure predictable releases and clear consumer notification are in place.
- Make sure the Developer Portal updates and release notes are up to date and on time with a clear record if the change is an enhancement or a bug fix or others like a customer issue.
As API backend developers
- Anticipate changes right from the first 0.0.1 version and build an architecture that can adapt.
- While changes can have far reaching effects especially to how data and databases are handled, new versions can help in bug fixes, removal of technical debt, and adoption of more efficient technology.
- Consider running different implementation versions side by side to handle the API versions.
- API version in content or headers can help downstream systems handle them correctly.
- Plan and design for changes that might be needed in databases.
As API consumers
- Keeping up to date with changing API versions will help in being able to leverage the latest features and functionality offered including security, and also helps in reducing technical debt.
- Keep abreast of upcoming changes based on developer portal notices and plan for them.
- Making large version leaps will be tedious, difficult, and risky to adopt; it is good to be agile in adopting new changes.
- Undertake impact assessment (are they breaking changes or non-breaking changes?) across all layers of your codebase.
- As a standard, ensure the consumer implements a tolerant reader pattern so that the software doesn’t break with what could potentially be be considered as a non-breaking change.
Managing critical impacts and considerations due to API evolution
Due to the extent of impact, new versions should never be taken lightly. A few areas that need careful consideration are:
- Be doubly sure that a new version is critical and there are no alternatives.
- When should APIs be versioned? Should the version change be a major, minor, or patch version change? Leverage semantic versioning to ensure version standardization.
- Which versioning strategy should be adopted. A few examples are URI versioning, header versioning, content versioning.
- Who are the key stakeholders and how to notify them? Does your API management platform provide tools to identify consumers so as to notify them?
- What can be done to facilitate smooth transitions for API consumers?
Red Hat 3scale API Management, Red Hat OpenShift, and tools such as Red Hat build of Apicurio Registry and Apicurio API Designer provide a solid foundation for API management and versioning. GitOps with Argo CD provides an efficient way of performing API management. GitOps centralizes API configuration management, automates the deployments with Argo CD, and empowers collaborative efforts through a shared Git repository.
See API versioning in action: try the solution pattern
Solution patterns from Red Hat help you understand how to build real world use cases with reproducible demos, deployment scripts, and guides.
In the API Versioning solution pattern, we introduce Globex, a fictional retail company, as it navigates the complexities of managing API versioning. Globex aims to seamlessly incorporate new versions of its API across all layers, ensuring a smooth transition for both backend systems and API consumers. Globex effectively manages API versioning challenges, for both internal and external stakeholders using a lot of the best practices and strategies discussed in this article.
Building intentional APIs with built-in versioning
The dictionary defines the word intentional as an adjective that means "done on purpose; deliberate."
This is great philosophy to adopt while considering creating APIs for internal or external stakeholders. Being intentional across the API life cycle—from designing to developing, versioning, and managing it—makes for simpler and greater adoption.
Go ahead and try out the API Versioning solution pattern.
