The document discusses best practices for API versioning, emphasizing the importance of careful planning and communication regarding changes that may necessitate new versions. It advocates for maintaining existing functionality while introducing new capabilities and recommends strategies such as semantic versioning to minimize disruption for API consumers. Additionally, it outlines the necessity of sunsetting outdated versions and effectively managing the transition to new API versions to ensure a smooth experience for users.

1. VERSIONING
VERSIONING
VERSIONING
BEST PRACTICES
BEST PRACTICES
BEST PRACTICES
FOR API
FOR API
FOR API
newsdata.io

2. 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.
Newsdata.io API

3. 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!
Rule of Thumb for API Versioning
Newsdata.io API

4. 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.
Tip #1 — Keep a Detailed & Up-to-date
API Spec
Newsdata.io API

5. 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.
Newsdata.io API

6. Keep existing applications’ existing functionality(s).
Provide new API versions with additional functionality(s).
This is to handle the evolution of APIs (enhancements, bug fixes) over time. Software
engineers can use versioning strategies to do the following:
Tip #2 — Devise a Versioning Strategy
Newsdata.io API

7. Newsdata.io API
Change responses (payloads) cautiously.
Accept requests from applications/consumers with open arms.
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:

8. Consumers are reliant on the calls/methods that the changes entail.
The following consumer characteristics should be reflected in the design:
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:
- Models
- Mental images
- Predictions
#TIP4: Surprises are not Good! In the API
world at least
Newsdata.io API

9. 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.
Software engineers can do the following to reduce surprises (or astonishment):
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.
Newsdata.io API

10. 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).
Newsdata.io API
Tip #3 — Try to use Semantic Versioning

11. 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.
Newsdata.io API

12. Newsdata.io API
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
Using Semantic Versioning
We can do the following with Semantic Versioning:

13. Newsdata.io API
Domain
Sub-domain
Version
Useful resource
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.
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.
2.
3.
4.
In my opinion, and based on my experience, I recommend including the major version
number in the basePath for the following reasons:

14. Newsdata.io API
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.
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:

15. Newsdata.io API
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.
So, by updating the basePath for new API Specs, software engineers can support
and catch the following scenarios:

16. 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..
Newsdata.io API
Tip #5 — Handling and Onboarding
Breaking Changes

17. 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.
Newsdata.io API

18. Adding one to the minor version
Reverting the patch version to zero
Engineers typically perform the following updates for minor version changes:
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)).
Newsdata.io API
Tip #6 — Handling and Onboarding Non-
Breaking Changes

19. 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.
Newsdata.io API

20. 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.
Newsdata.io API
Tip #7 — Gracefully Sunset and
Deprecate legacy API versions

21. 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.
Always try to do the following when sunsetting and deprecating APIs for the best
customer service:
Newsdata.io API

22. Newsdata.io API
Reference
1. https://abdulrwahab.medium.com/api-architecture-versioning-best-practices-
1d5cea49df25
2. https://newsdata.io

23. Newsdataio
Newsdata.io
Newsdata.io
Newsdata_io