API Versioning and Its Guidelines in Anypoint Platform
API endpoint URL, and Anypoint API Manager entries in "API version", "Implementation URL" and "Consumer endpoint".
Join the DZone community and get the full member experience.Join For Free
In What Part of a URL to Surface the API Version:
- Encode the version just in the URL path, e.g., http://mypoliciessummarypapi.cloudhub.io/v1
- Demands a DNS lookup of ans-policyholdersummary-papi.cloudhub.io to propose an API implementation (or API proxy) that encourages all version of the API, including planned major versions
- Alternatively, all API invocations must be routed on the server-side to the API implementation that promotes the demanded version.
- Promoted through URL mapping rules in Cloudhub Dedicated Load Balancers.
- Encode the version just in the host-name, e.g., http://mypoliciessummary-papiv1.cloudhub.io/
- Allows infinity (major) versions of the API to be stiffened by different API implementations (or API proxies) externally having to do URL recasting.
- Encode the version in the hostname and the URL path, e.g., http://mypoliciesummary-papi-v1.cloudhub.io/v1
- Redundant but allows the URL path on its own to distinguish the requested API version, without URL rewriting.
- Concedes the same API implementation to expose endpoints for more than one major version.
API Versioning Guidelines:
The Acme Insurance C4E defines the following API versioning guidelines, which are fully supported by Anypoint Platform:
Only reveal major API versions as v1, v2, etc. in RAML definition, API endpoint URL, and Anypoint API Manager entries in "API version", "Implementation URL" and "Consumer endpoint".
- In the API endpoint URL expose the major API version only in the URL path
- E.g., http://mypoliciessummary-papi.cloudhub.io/v1
- Claims future major versions to either be implemented in the same API implementation or to route API invocations by URL mapping rules
- To be increased as and when the need arises with Cloudhub Dedicated Load Balancer supported URL mapping.
- Publish to Anypoint Exchange using the full semantic version in "Asset version", and refer to that from Anypoint API Manager "Asset version".
Hope it help.
Opinions expressed by DZone contributors are their own.