IT modernisation series – Rubrik: versioning as part of the modern API lifecycle
Unlike digital-first organisations, traditional businesses have a wealth of enterprise applications built up over decades, many of which continue to run core business processes.
In this series of articles we investigate how organisations are approaching the modernisation, replatforming and migration of legacy applications and related data services.
We look at the tools and technologies available encompassing aspects of change management and the use of APIs and containerisation (and more) to make legacy functionality and data available to cloud-native applications.
This post is written by Rebecca Fitzhugh in her role as director of developer relations at Rubrik.
Fitzhugh addresses the fact that Application Programming Interfaces (APIs) have become a key part of the modern software application development process where they function as an essential ‘glue’ to bind different services, components and functions together – so, as such, APIs themselves must now be regarded as having their own lifecycle. Without a programmatic approach that embraces, recognises and understands the flow of the API lifecycle, developers are (arguably) doing themselves a disservice.
Fitzhugh writes as follows…
Given that we now accept, understand (and indeed welcome) the use of APIs in the modern development landscape, we must also recognise the fact that API changes are inevitable as a platform’s surface area grows.
Managing the impact of these changes can be challenging, but not doing so creates a poor developer experience due to mishandled breakages. Versioning does not prevent a breakage from occurring, however, it helps control where, when, and how the breakage occurs.
However, you must still update your code. So consider these questions when introducing a new API version:
- What are the reasons for creating a new version?
- How do you plan on communicating changes to consumers?
- Is the new version a better version?
To minimise toil experienced by your API consumer, treat the API as a product — even if you are not billing the consumer for usage. Consider the entire API lifecycle; this means having a clear progression into a semantically versioned API with a defined deprecation period and process. This will result in fewer headaches experienced by both your engineering teams and API consumers from experiencing uncommunicated disruptions.
Reasons to version
Leveraging API versions can help reduce the complexity and iterate quickly when required changes are identified. Any time a breaking change happens, it should result in a change to the version of the API. This includes when removing any part of the API, changing the response type and/or changing the response data format. Major version changes are likely unnecessary for non-breaking changes, such as adding new endpoints or response parameters.
With a good versioning strategy, it is possible for different versions of the API to coexist. This allows the API provider the opportunity to build and release the next API version before fully deprecating the previous.
It also enables time for consumers to rework their existing architecture to support the new API version.
Communication is key
Unplanned API changes will leave your consumers aggravated, or worse, could negatively impact their business.
If you plan to release a new API version, communicate that to consumers as soon as possible. Send a message announcing the new version, any intended deprecation, with details like the timeframe, changelog, support, and contact information.
Ensure that the sunset period for deprecation is clearly highlighted so that consumers can begin efforts to update code within that time frame.
APIs are effectively contracts once published. As the provider, you made a promise to not introduce breakages without sufficient notification.
A better version
Versioning is a critical part of your API strategy and design that can give your engineering team the capability over time to refactor and publish better representations for API resources.
You should certainly try to get your API as perfect as possible from day one, but keep in mind that “perfection” is ephemeral – changes will be required eventually. With an “API as a product” mindset, the API will follow a predictable lifecycle with an established set of practices for introducing new endpoints to deprecation.
As an API provider, you should put considerable thought into why, when, and how you manage support for an API version.
Listen to your consumer needs, they will tell you their use case(s) and point(s) of friction when using your API.
The success of your API is ultimately measured on the success of the consumer; Smartbear’s 2019 State of API Report divulged that over 50% of consumers stated that speed or cost was the primary driver for using an API.
This means by making your API easier to use, you’re investing in customer satisfaction.
Fitzhugh: An API is a ‘contract’.