Scribd
Upload
107 views

Best Practices For API Versioning

This document provides best practices for API versioning, including when to introduce new major and minor versions. It recommends introducing a new major version for backward incompatible changes that require updates to consumer interfaces, while minor versions can include backward compatible changes or additions. Patch versions are for backward compatible bug fixes. The API version should be included in the URL to allow consumers to specify which version to call.

Uploaded by

RameshCh
Copyright
© © All Rights Reserved
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
107 views

Best Practices For API Versioning

This document provides best practices for API versioning, including when to introduce new major and minor versions. It recommends introducing a new major version for backward incompatible changes that require updates to consumer interfaces, while minor versions can include backward compatible changes or additions. Patch versions are for backward compatible bug fixes. The API version should be included in the URL to allow consumers to specify which version to call.

Uploaded by

RameshCh
Copyright
© © All Rights Reserved
Available Formats
Download as DOCX, PDF, TXT or read online on Scribd
You are on page 1/ 3

Best Practices for API Versioning

An API should be designed for long term use, but because change is inevitable, the
API can never be completely stable.
It is important is to manage the changes through a comprehensive versioning
strategy. This includes a multiple month deprecation schedule and documentation
that is up to date and describes the change in sufficient level of detail.
Not all changes require a new version. APIs designed for backward compatibility
normally do not require major changes and should use minor or patch changes.
It is not always possible to design APIs in that way. The table below outlines when to
introduce a new version and when a new version is not required. Typically when one
clicks Add new API operation a minor version increase occurs.

Changes Not Requiring a New Major


Type of Change Changes Requiring a New Major Version
Version

Service contract o Remove API endpoint Add new API operation


o Change in the effect of an API operation
o Change in the response type of an API operation
o Add new required operation argument
Data contract o Remove an existing element (or attribute) o Add an optional element (or attribute)
o Add new required element (or required attribute) o Add a derived element type
o Change an existing element (or attribute)
Representation Remove existing representation Add new representation
format
Accessibility Restrict permissions Relax permissions

When to Introduce a New Major Version


You should introduce a new major version for:
o Quality of service (QoS)
When a change affects the quality of service, such as response time and availability,
the change might not be backward compatible with the API’s applications, so you
might need to change the API’s major version and API version.
o Output message domain value changes
Applications that use the API depend on the domain of values of fields in response
messages. For instance, the API might return only certain products or specific
payment methods. If the API starts returning values outside of a domain, it can
adversely affect existing consumers. In this case, consider introducing a new major
version and a new API version.
When to Change Version Numbers
o Major versions
When introducing a change in the structure of the API that requires the user of the
API to adapt the interface on the consumer side, such as a new required operation
argument
o Minor versions
When introducing a backward compatible change to the API that does not require an
API user to change, such as a new optional element
o Patch versions
When introducing a backward compatible bug fix or documentation update
See Semantic Versioning for more information.

API Version in Application URL


Include the API version in the application URL so that consumers can choose which
version they want to call.
o For on-premises deployment, the version is in the base URI and appears in the URL:
http://www.example.org/v1/api/customer/1234

Naming Conventions
Use these rules to define an API version:
o Specify the version with a "v" prefix.
o Use a simple ordinal number, for example, "v1","v2", and so on.
o Avoid using dot notation, for example, "v1.2".
o Only specify the major version as part of the URL.

Document an API Version


Exchange provides documentation pages with information about an asset for API
consumers. You can create different documentation pages for each minor asset
version.
Select a minor asset version to edit with the menu next to the version.

Policies Overview
See the Included Policies Directory for descriptions of all included policies.
Policies differ based on several different factors, such as category, purpose, version,
and configuration options. Carefully consider these factors before you implement
them in your environment.
Based on the Mule runtime engine (Mule), a policy Exchange asset is consists of:
o Mule 4:
o A deployable JAR file that contains the policy business logic.
o A YAML configuration file, in which the policy parameters and metadata are defined.
o Mule 3.x:
An XML file that contains the policy business logic and configuration parameters

You might also like