An Application Programming Interface (API), regardless of the technology used to create it, should be versioned to allow flexibility for growth and changes. Over time, many endpoints in your microservice suite will change. Many changes are additional data being returned, which will not cause heartburn to existing service consumers.
An API version is mainly to mitigate “Breaking Changes.” During an API endpoint’s lifespan, changes will happen. Additional parameters and changes to the return value format may be added. If a change makes the current usage of the endpoint no longer work, then that is considered a breaking change.
Don’t Rip up the Contract
A contract is the parameters an API accepts and the data format returned, if any. In software development, the format needed to call a function is called the signature; you may also hear developers refer to the request and response format of an endpoint with this term as well.
Breaking Change in the Request
If an endpoint has a new query string parameter added that is required, existing callers will fail if you release that change to production. The same goes for an existing parameter that is currently optional, being switched to required. Any consumers who are sending that parameter may not notice the change, but consumers who are not will now get errors.
If the endpoint accepts a payload, as in a POST, PUT, or PATCH, any major changes to the payload format will be a breaking change. For instance, if your customer endpoint has a change to the new customer input, such as a new required field of “MaritalStatus,” then existing consumers of this endpoint will get an error when attempting to save a new customer.
Breaking Change in the Response
Most API endpoints have a response. In the example above, a call may be made to a customer endpoint passing a customer number, and customer data will be returned in a format called a Data Transfer Object (DTO).
Let’s say the Customer DTO had an address such as AddressLine1, AddressLine2, City, State, and PostalCode. You plan to change the Customer DTO to have the address be a collection of addresses. This will allow a customer to have different shipping and mailing addresses. The above-mentioned fields will be removed from the DTO. This is a fundamental change to the structure of the return and will cause the consumers of this endpoint to fail because their code will not be able to cope with the new format for reading an address.
Backward Compatibility
Preserving Existing Integrations
As APIs evolve, changes can break existing applications that rely on the older versions. Versioning allows developers to continue using the older API version while new functionality or changes are introduced in a new version.
Smooth Transitions
By maintaining older versions, developers can upgrade their applications to newer API versions at their own pace rather than being forced to adapt immediately.
Controlled Evolution
Introducing New Features
New versions can introduce new features, enhancements, and optimizations without disrupting the existing functionality.
Deprecating Old Features
It provides a structured way to gradually phase out outdated features or approaches. Deprecated features can be maintained in older versions while encouraging migration to newer versions, where they are removed or replaced.
Bug Fixes and Security
Security Patches
Versioning allows for targeted security updates. Critical patches can be applied to specific versions without affecting other versions.
Bug Fixes
Similar to security patches, non-critical bug fixes can be applied to specific versions without altering the API contract in other versions.
Enhanced Flexibility for Clients
Choice for Developers
Client developers can choose which version of the API best suits their needs, giving them control over when to integrate new features or updates.
Testing and Validation
Different versions allow for more rigorous testing and validation processes for specific versions, ensuring that new versions are stable before wider adoption.
Clear Communication
Explicit Changes
Versioning communicates that changes have occurred. While many software types have major and minor version changes, API endpoints only need to change their version for major events. The minor changes for enhancements and added features do not require a version change if they do not affect the current consumers of the endpoint(s).
Documentation Clarity
Versioned APIs can have separate, clearly defined documentation for each version, making it easier for developers to understand each version’s specific behavior and features.
Avoiding Breaking Changes
Minimizing Impact
Existing clients using older versions remain unaffected by introducing breaking changes in a new version. This minimizes the impact on users and allows a more seamless API evolution.
Lifetime of an Endpoint Version
The introduction of a new endpoint version often introduces new functionality or features. However, there are times when the change is necessitated by a change to an underlying application or data store that makes maintaining the old version problematic. In some cases, I’ve experienced where the version must be upgraded due to a federal regulation. In these cases, the new version should be introduced as soon as possible to give developers that consume the endpoint time to implement the new version before the old version is sunset.
Versioning Methodologies
In practice, API versioning can be implemented in several ways, including:
URL Versioning
Adding the version number in the URL path or route is probably the most popular versioning method and is the preferred method used by Yasgar Technology Group.
api.example.com/v1/customers
Header Versioning
Including the version number in the HTTP request headers.
X-API-Version: 1
Query Parameter Versioning
Adding the version as a query parameter.
api.example.com/resource?version=1
Each approach has pros and cons, but the underlying goal remains: to provide a stable, predictable, and flexible API environment for developers and users alike.
