Azure API Management - Revisions vs Versions

-
A lot of us would already be familiar with Azure API Management and might already be using it extensively as a gateway for our backend services.

"API Management (APIM) is a way to create consistent and modern API gateways for existing back-end services. You can use Azure API Management to take any backend and launch a full-fledged API program based on it." - Official Microsoft Documentation

It is fairly easy to set-up and get started. But then over time, when the backend services or API goes through evolution, arises the need to have continuity while at the same time being able to make available updated APIs and/or backend services.

If you are not familiar with Azure API Management, I recommend reading the Official Microsoft Documentation.

Microsoft announced the public preview of "Versions and Revisions in Azure API Management" on September 14, 2017. 3 years later, I see that there are still quite some questions on the effective use of these features in a lot of enterprises.

In this blog, I have tried to put together a strategy to handle this based on information that I have gathered from Microsoft Official Documentation and blogs. Of course this is completely my understanding and view of using these features. I am eager to also know and understand how others handle this to augment my understanding or maybe completely change it.

Let us first understand what is meant by Revisions and Versions and then try to understand how they can be used in the flow of rolling out changes to your APIs.

Firstly, Versions and Revisions are two distinct , yet related, features.1

What are Revisions?

Revisions allow you to make changes to your APIs in a controlled and safe way. When you want to make changes, create a new revision. You can then edit and test API without disturbing your API consumers. When you are ready, you can then make your revision current – at the same time, you can post an entry to the new change log, to keep your API consumers up to date with what has changed.1
  • Revisions are changes/improvements/fixes to the current available API i.e. non-breaking changes.
  • Revisions allow to safely make changes to your API Management API definitions & policies, without disturbing your production API.
  • Revisions allow to try out changes before publishing them.
  • After testing, 
    • A new Revision can be set as current i.e. published. Thereafter, the new revision is available to callers of API.
    • Rollback if you find issues.
  • Notes/descriptions about changes made in a Revision can be published to Public Change Log of the API.
  • This information is available in the developer portal and acts as change-log that developers can refer/use.

What are Versions?

Versions allow you to present groups of related APIs to your developers. Versions differentiate themselves through a version number (which is a string of any value you choose), and a versioning scheme (path, query string or header).1
  • Version is in fact a new API based off an API's revision.
  • Every version gets a new name that must be unique across API Management instance.
  • Versions allow to publish multiple versions of your API at the same time.
  • Versions can introduce major changes that can be seen as breaking-changes.
  • Versions can be seen as new APIs which can
    • use path/query string or header to differentiate between versions.
    • use any string value you wish to identify your version (a number, a date, a name).
    • be associated with different products.
  • Show your API versions grouped together on the developer portal.

Revisions vs Versions


Each version can have multiple revisions, just like a non-versioned API. Should you find that your revision has breaking changes, or if you wish to formally turn your revision into a beta/test version, that is also possible.

Now that we have an understanding of what they mean and how they can fit into the plan of things, it might also me meaningful to try and list scenarios where Versions and Revisions fit - when to use what?

When to use Revisions?

  • When you need to fix/add/update your current API without disrupting the callers i.e. make non-breaking changes.
  • Such changes can be Policy Changes, Addition of new operations, etc.
  • You can only support and expose one Revision at any one time.

When to use Versions?

  • When you want to introduce a breaking change to your API and deploy it as a new API with a new URL.
  • When you have different versions of URL intended for different audiences/Products.
  • You also want to support all/more than one such deployments – old and new.

Text Quotes

References:


Comments

Post a Comment

Popular posts from this blog

Automate Import of Functions/WebAPI in Azure API Management as backend and using OpenAPI definition and Terraform

-
Image
 When hosting APIs in Azure it is more and more common to make them available for consumption via an API Management Gateway. The advantages of using a API Management gateway are well known.  When adding a Function/WebAPI to an API Management gateway, the most common method is to add the Function/WebAPI as a backend in API Management and then exposing the Function/WebAPI as an API that uses this backend to process requests. There is a very simple way to do this using the Azure Portal. The portal allows connecting an existing Function or WebAPI inside the API Management gateway.  The portal now also allows to expose a function/web api from the action pane of functions and web api. While this makes it very easy to add APIs to API Management gateway using the portal, this would very soon become unmanageable and for more complex and automated environments, the obvious tilt would then be towards a automated deployment using one of the Infrastructure as Code (IaC) possibilities. In this examp
Read more

Transcripts with Microsoft Bot Framework v4

-
Image
For those that have been working with conversational interfaces namely bots, both developers and business users, have at some point come across the term transcript. So what is a " bot transcript file "? According to docs.microsoft.com, "A bot transcript file is a specialized JSON file that preserves the interactions between a user and your bot. A transcript file preserves not only the contents of a message, but also interaction details such as the user id, channel id, channel type, channel capabilities, time of the interaction, etc. All of this information can then be used to help find and resolve issues when testing or debugging your bot." If we look closely at this definition, we can see that a transcript is much more than just contents of messages exchanged between user and bot. It contains a lot more information in it's raw form. Thereby, it is quite evident that a transcript has use for both business users and developers. How can a business user use
Read more

Managing built-in cache in Azure API Management

-
Image
 Azure API Management offers caching possibilities to improve performance.  There are 2 caching options: Response Caching - Useful for caching entire HTTP responses Value Caching - To cache arbitrary pieces of data from within policy definitions. When it comes to the actual store, APIM supports: Built-in cache External Redis Compatible cache In this blog I will focus on how to manage "Value Caching". How do we set/retrieve/delete values using APIM policies? Typically, Value storage is used for fragment caching - where responses contain data that is expensive to determine and yet remains fresh for a reasonable amount of time. Also, within the APIM policies, we want to cache certain values e.g. OAuth tokens, key-vault secrets, etc. because these remain relatively fresh for a longer period of time. With caching comes the need to manage the cache specially when you need to clear cached values because they are stale.  In some scenarios, where OAuth tokens or secrets are cached, yo
Read more