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.

1. 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?

2. 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.

3. 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

4. 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

5. 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

6. 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:

7. • 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.

8. • 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

9. 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

10. 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