This is a question that comes up a lot during my discussion with prospects. And rightly so, since versioning is a very common and a real concern for any API Program. The whole premise of being Digital is that, it is really hard for you to get all your end users upgraded to the latest version of your app, let alone getting all the different partners and their end customers honoring your end of life notices.
Even before getting into versioning use cases that I have seen across various API programs I wanted to talk about analytics and API products.
Analytics is a very powerful tool, to give you visibility into how the usage has been for the API across different version. You can create custom reports that can tell you which developer, which developer app is using the older version of the API.
API Products can be leveraged effectively to restrict the newer apps being built, either by you or your partners from using the older versions of the API. Even if they have to use the older version of the API, you can put appropriate rate limits at the product level to give them an incentive to move to the newer versions of the API.
Beyond these best practices, at a high level, I’ve seen these four standard versioning use-cases with respect to API versioning itself:
1. Backend Supports multiple versions, Apigee does a pass through
This is a straightforward case, where the API Provider supports multiple backend versions and Apigee has to just pass them through. The only value add Apigee brings on to the table is visibility, in terms of how various versions are being used.
2. Backend Supports multiple versions, Apigee routes to the appropriate version
This is more of a content/context based routing - where Apigee can route the request to the appropriate version. This routing can be done based on a logic that Gateway can apply on the incoming request based on various parameters like URL/Query Paramaters/headers/payload elements/client ip/authentication information etc.
This will give a flexibility on how you manage the versions at the backend (like changing the url paths, moving them to new hardware etc)
3. Backend supports one version, Apigee does the mediation
In cases where it is expensive to manage multiple backend versions, Apigee can mediate the request/responses. That way, the backend gets the request in a way it understands, and the clients get the response in the way they expect. This is recommended as long as the mediation rules are straightforward (and simple).
4. Apigee gives an error for API requests for older versions
In cases where maintaining older versions is not viable and the transformation rules can become very complex (this happens when most of your clients update themselves to newer versions), Apigee can give a (meaningful) error response to the clients who still use the old version (that the provider stopped supporting)
This can also be done is a phased manner where
Phase 1 - Apigee adds a header or some other non intrusive way- to tell the developer that the API will be depriciated
Phase 2 - Apigee can introduce stringent rate limits on older version
Phase 3 - Apigee can block the requests and send the appropriate error message
Feel free to leave your comments and experience with API versioning.
LinkedIn
Twitter