Best Practices For API Versioning

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

Best Practices For API Versioning

Uploaded by

Copyright:

Available Formats

Best Practices For API Versioning

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Best Practices For API Versioning

Uploaded by

Copyright:

Available Formats

Best Practices for API Versioning

Changes Not Requiring a New Major

Service contract o Remove API endpoint Add new API operation

When to Introduce a New Major Version

API Version in Application URL

Document an API Version

You might also like