Data, surely is the new oil. APIs are the hoses through which that data is transported. RESTful APIs have become popular as they promote easy adoption & integration. For an enterprise that wishes to expose its services via APIs, it is important that those APIs are organized to promote discoverability, meaningful versioning, and security. In this blog post we will look at Azure API Management product and the various organizational constructs that it provides to help enterprises address this challenge.

Let us take the example of a fictitious library to illustrate. The library lends books but not periodicals. Periodicals have to be read at the library. The library is funded by Patrons. These patrons could either be life time members or guests who pay per lending. We consider two separate APIs to illustrate the concepts. A Catalog api that helps with populating catalogs and a patrons API that helps with managing patrons.

In Azure API Management, an individual REST call (GET / PUT / POST / DELETE / PATCH) is termed as an OPERATION. Several related operations makeup an API. As an example, in the picture above each of APIs books, periodicals, guests, lifetime members have individual RESTful CRUD operations.

Several related APIs can be combined together to form a PRODUCT. As an example, the books and periodicals APIs are grouped together into a product called Catalog.

TAGS can be used to further enhance the metadata. TAGS can be applied either at the API or at an individual OPERATION. As an example, a tag named tag1 is applied in the picture.
A PRODUCT can now be published and exposed to the external world. Once a PRODUCT has been published, there are two constructs that help with effective change management.

A REVISION can be used work upon an existing API Operation without impacting the developers who might already be using that API. Once the REVISION is ready, it can be promoted in place of the existing OPERATION. As an example, let’s assume there is a bug in the patrons API and it is not updating address details for newer patrons. The developers can continue working on the bug fix on a new version and then promote that new version of the API once it is ready.

APIs change over their life time. Their input and output formats might change for instance. If these changes are made to existing APIs without warning, one might end up breaking all the applications that depend on the shape of that API. VERSIONS can be used to introduce such changes. As an example, if we decide to change the api shape for our periodicals API, then that would be a breaking change. A new version of the API can be created to introduce this change. The older versions will continue to operate as is and will not break workflows for existing developers.

API Management is integrated with Azure Active Directory. As such Authentication and Authorization are handled by AD. All the constructs that we have examined, OPERATIONS, APIs and PRODUCTS offer support to be protected by Azure AD via OAUTH 2.0 and which we shall examine in a subsequent blog post.