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