Versioning Best Practices for API Architecture

 

Let us begin by admitting that API Versioning is a difficult task. For APIs like Newsdata.io news API Development teams can make a variety of changes to an API throughout its lifecycle (enhancements, bug fixes, adding new capabilities, etc.).

How would you know whether a particular change necessitates a new API version? How would you convey this to customers? How much time would consumers have to make the switch?

All of these questions can be answered with careful planning.

Rule of Thumb for API Versioning

Each time you improve your API, it evolves. And API evolution can either keep your API implementation the same or introduce breaking changes that negatively impact your API consumers.

To keep consumers happy and APIs functional, you must decide on a versioning method, how to version your APIs, and what general principles to follow when upgrading your APIs.

Without further ado, let’s get started!

Tip #1 — Keep a Detailed & Up-to-date API Spec

An API Specifications document contains the following information for software engineers and end-users:

Contract — An API Spec is a contractual agreement between API software engineers and API consumers (or applications). It should include information about all of the API features that are made available to the application.

Operations — The specific operation(s) supported by the API, also known as methods and functions.

Requests — The specific request(s) that the API supports, as made by applications.

Responses — The specific response(s) supported by the API and expected by applications.

If the API service does not comply with the agreed-upon corresponding API Spec, an application will not function properly with it.

Tip #2 — Devise a Versioning Strategy

This is to handle the evolution of APIs (enhancements, bug fixes) over time. Software engineers can use versioning strategies to do the following:

• Keep existing applications’ existing functionality(s).
• Provide new API versions with additional functionality(s).

How to handle the versioning

When it comes to versioning your API, as a software engineer, you should consider the following concepts:

Postel’s Rule

Postel’s law suggests the following when implementing versions:

• Change responses (payloads) cautiously.
• Accept requests from applications/consumers with open arms.

Surprises are not Good! In the API world at least

When determining whether an API change is of the breaking variety, you should apply the Principle of Least Astonishment and keep the following guidelines in mind:

• Consumers are reliant on the calls/methods that the changes entail.
• The following consumer characteristics should be reflected in the design:

- Models

- Mental images

- Predictions

Software engineers can do the following to reduce surprises (or astonishments):

• Make the API meet the consumers’ current expectations.
• Create and implement new features that will behave in accordance with existing mental models created by consumers and end-users.

If teams stray too far from an existing mental model, they may conclude that a potential change is a game-changer, even if they consider it minor/harmless. This is due to the fact that the consumer and end-user lack the underlying system knowledge that the software engineer supporting the API possesses.

Tip #3 — Try to use Semantic Versioning

Semantic versioning is a strategy that enables engineers to create patches and minor version changes without disrupting existing integrations.

Updates to patches

Patches are API changes that do not affect the API’s functionality. It could be as simple as adding a new dependency.

Minor alterations

Minor changes may add some new functionality, but they rarely result in breaking changes (ex: a newly required field).

Significant modifications

Major changes are those that necessitate application developers/consumers changing how they call and consume an API (for example, providing a required parameter(s) in an endpoint).

The effects of versioning

Versioning changes are costly and time-consuming for both the software engineers who build and support the API. Additionally, the applications/consumers that use the API require long timeframes to properly test and ensure the upgrades are working with the application as desired.

Using Semantic Versioning

We can do the following with Semantic Versioning:

• For versioning, use the following pattern to identify our APIs: Major.Minor.Patch
• Release your API specifications in stages, with the first version being 1.0.0.
• Versions created prior to the initial release are denoted as 0.x.x.
• - An important note: The 0 indicates that the API was still in development mode.
• Minor and patch versions are numbered sequentially beginning with 0.
• When the next higher version change occurs, restart the numbering for minor and patch versions at 0.
• When creating your API, include the major version number in the path

You can use pretty much any design strategy for your endpoint base (also known as basePath), but here’s what I’ve seen work frequently:

1. Domain
2. Sub-domain
3. Version
4. Useful resource

In my opinion, and based on my experience, I recommend including the major version number in the basePath for the following reasons:

• Semantic versioning will limit the ability of the API software engineer to update and change the API Spec and existing APIs.
• Breaking changes SHOULD NOT be introduced in minor and patch versions.

Versioning your URIs

My personal recommendation is to use URI Versioning to preserve previous versions of an API while migrating your consumers to newer API versions.

When updating versions, keep the following points in mind:

• Consistently indicate the version(s).
• Separate different resources.
• Create a new API call whenever the software engineer wants to provide a newer version of the API Spec.
• Maintain the functionality(s) of applications that used the previous API.

So, by updating the basePath for new API Specs, software engineers can support and catch the following scenarios:

• Existing APIs can be preserved by software engineers.
• To support the new API Specs, engineers can create new API endpoints.
• The version change has no effect on applications that have not fully transitioned to the updated URI.
• Existing consumer applications can continue to operate normally.

Tip #5 — Handling and Onboarding Breaking Changes

Breaking changes typically result in an increase in the major version number, while non-breaking changes result in an increase in the minor version number.

When rolling out/changing the major version number, you must consider all of your existing API consumers.

When releasing a new version of an API, many software engineers “sunset” the current version.

During the sunset phase, software engineers run the previous version of the previous API version alongside the new API version.

The API sunset phase, allows API consumers to gradually migrate to the new version.

Tip #6 — Handling and Onboarding Non-Breaking Changes

Engineers typically perform the following updates for minor version changes:

• Adding one to the minor version
• Reverting the patch version to zero

Patch Changes

API Specs would only include patch changes if the updates would have no effect on the Spec’s functionality (for example, typos in the description or other types of errors that do not affect general functionality(s)).

Routing changes

You can change the URL endpoint, and the correct API call will be routed automatically. To accomplish this, I always recommend including the version in the basePath. Finally, you must contact your downstream API consumers and request that they update the new basePath when you require them to use your new API version.

Tip #7 — Gracefully Sunset and Deprecate legacy API versions

When you release an upgraded version of an API, you should deprecate the previous versions so that you don’t have to maintain two service implementations for the API.

When an API is sun-set, it enters a limited-maintenance mode, giving API subscribers time to migrate to a newer version of the API.

Software engineers should provide a sunset and deprecation policy, stating the policy for any sunset period upfront.

Always try to do the following when sunsetting and deprecating APIs for the best customer service:

• Make an announcement informing all API users that they must upgrade to the new API version. This notice should include any sunset period and the date you intend to discontinue the service. Maintain an up-to-date list of your API consumers’ contact information.
• Sunset the API with a warning indicating the sunset time (ex: 1 month, x number of weeks, etc.).
• Deprecate the API once users have stopped using previous versions.

Reference and Credits

1. https://abdulrwahab.medium.com/api-architecture-versioning-best-practices-1d5cea49df25

2. https://newsdata.io