In the Microsoft Azure cloud platform we have a few features where the term API is involved in the name. In particular API Management and API Apps. In this article I would like to talk about Azure API Apps (API App) and Azure API Management (API-M).
These are both key features you are likely to be considering in your API and Integration strategies if you are an Azure user. I think it’s important to understand each and where they fit and how they complement and contrast each other.
If we look at the 2 features at a very high level and tried to give an elevator pitch at what each one is, I would describe them as follows:
API Apps is an Azure feature which is intended to provide you hosting and features to deliver the implementation of an API component.
API Management is an Azure feature which you can optionally place in front of an API which has been implemented on Azure (or another platform) to provide some more sophisticated features designed to improve the manageability and client experience when consuming the API.
Now that we have a high level view of the features, let’s take a look at some lower level detail.
Azure API Management
Azure API Management is a feature on the Azure platform which is intended to be placed in front of an existing API component to act as a proxy to the API. Once you have a proxy in front of the API you can then add some features to the processing of calls to the API to allow you to manage the use of the API.
Common Use Cases
Let’s take a look at a few common use cases for Azure API Management:
- Managing my own API
- Managing an external API
Managing My Own API
In this case I will have chosen to develop my own API and then before I allow anyone to consume it I will place the Azure API Management service in front of my API component so that I can provide a better experience with the use of the API for both myself and the consumers of my API. If we consider the diagram below, you can see this illustrates that we have created an API which may contain some of our logic. We do not allow the clients to consume the API directly and probably do not even tell the consumer where the API actually is located. Instead we sit Azure API Management in front of the API and connect it to our API. We then give the consumer access to the Azure API Management developer portal where they will have “managed” access to our API.
In the case above we have created an API called “My API” and the consuming application in our partner organisation does not directly talk to My API but instead makes HTTP calls to the API Management service. APIM then acts as a gateway to control access to our actual API components.
In this use case we need to consider that we may have many different consumers of our API, the API Management proxy can give us a number of features to manage these individual consumers separately so they all get the right experience. Some of the features we are likely to use include:
- We might require consumers to go through a registration process using the API Management developer portal to ensure we only allow approved consumers
- We can create a great experience for our API consumers by creating a branded developer portal with documentation and samples and a test client
- We may choose to implement caching on some API operations
- We may allow some users to only see certain operations or methods on the API
- We may implement transformations such as a GET to POST or header manipulation (or other options) between the gateway and the actual API
- We might require different users to have different API access keys
- We may even use APIM to expose a virtual API which flows calls to multiple different backend apI’s
The key point here is the APIM service allows us a place to implement many high value features which would be difficult to implement in every API component we produce.
Managing an External API
I may choose to place APIM between calls from an application in my organisation to an API provided by someone else. It would look something like the below diagram.
To explore this idea further, imagine a scenario where I pay for a subscription to access an API which tells me the current weather. If my subscription only allowed me to call the API 1000 times per day but I wanted to consume the API in multiple applications then one approach I could take would be to make all applications make the call through APIM. This would give me a few opportunities in this scenario such as:
- With APIM I can get monitoring and analytics of which application is calling the API when
- I may choose to implement caching in APIM so that the number of calls to the weather API would be reduced significantly and most of the time applications would use a cached response
- I may choose to implement rate limiting so that 1 application can call the API more often than another
There are many benefits to managing your applications accessing external API’s through a managed service such as APIM rather than directly even if you only use it for governance and monitoring
Azure API Apps
An Azure API Apps is a newer feature than API Management. Azure API Apps is a specialisation of the Azure App Service which is provided to help host API components. It is similar to how Web Apps and Mobile Apps are specialisations of App Service to host web and mobile apps.
The terminology though is a little more confusing than that because as well as a section of the App Service Hosting Plan on Azure being described as API Apps, there are also types of components which are called API Apps. This means you can build an API App component and then deploy it to Azure API Apps.
An API App component is a specific type of REST service which is designed to run on the Azure App Service as an API App. Being an API App component allows the REST API to be able to inherit and use some features offered by the Azure App Service platform. The main characteristics of a component which allow it to be an API App are:
- It is a REST API
- It uses Swagger to document its interface and to support discovery by the App Service
- It is hosted on the Azure App Service
It may support one of the following patterns:
- Connector – An API that can be used to connect to an external resource. This is a bit like a proxy service to something like a SaaS application or using hybrid functionality to access an on premise system.
- Trigger – An API that a logic app can call to trigger a workflow when a condition is met
- Action – A type of API app which would usually be used by a Logic App to to execute some kind of functional logic
- The API App will live within a resource group on App Service
The API App will be accessed via the Gateway which controls admin and authentication to the API App.
An API App component will look like the below diagram.
In the diagram there are 2 API apps within a resource group. The API Apps would be accessed via a client which could be external such as a Web App or perhaps a Logic App within the resource group. Access to the API App is always via the Gateway.
There are also a number of different flavours of API App components:
- A simple custom developed API App
- A custom API App intended to be consumed by Logic Apps
- An out of the box API App
- A marketplace API app
- Community API Apps
We will explore some of these flavors next.
A simple custom developed API App
An API app can be developed in any technology that you can use to develop a REST API such as ASP.net, Java, PHP. At its most basic form a component deployed to the App Service as an API App would inherit logic offered by the API Gateway and App Service runtime environment for things like resource group management, diagnostics and other features.
Also If you were to use Visual Studio to develop your API App then you can leverage the project template for API Apps which gives you a lot of out of the box features setup such as Swagger setup through integration with the Swashbuckle NuGet package. Great debugging and testing tools and also the ability to easily deploy to App Service through Visual Studio deployment and integration with Visual Studio Online for continuous deployment.
A custom API App intended to be consumed by Logic Apps
There are certain ways you can build your API App which will allow you to leverage more features offered by the Azure App Service for API’s. In order to be consumed by Logic Apps the API App needs to follow one of the patterns connector/trigger/action and also provide a Swagger interface.
Integration with Swagger means your API App would have dynamic documentation which would allow you to leverage the discovery features used by Logic Apps to consume API Apps. A simple API app can also offer a swagger interface but this is not mandatory. If you want your API App to be consumed by a Logic App then it would need to offer a swagger interface to allow it to provide the meta data required by the logic app.
By choosing this option to build your API App in a certain way then it can be combined with other technologies such as Logic Apps.
An Out of the Box API App
In addition to API Apps you may build yourself, Microsoft has also provided a toolbox of API Apps which you can use. These API Apps are also implementing one of the three types identified above connector/trigger/action. Microsoft have identified a range of common integration scenarios which customers will require and provide an API App to connect to that app. The out of the box API Apps provide connectivity to many of the common SaaS applications and also on premise applications by using hybrid integration patterns. The below diagram shows an example of how a logic app may consume API Apps to connect to other systems.
BizTalk Integration API Apps
In addition to the connector and trigger style apps, there are also a premium range of BizTalk style API Apps which are intended to complement the basic integration capabilities with enterprise integration capabilities which you are used to with the BizTalk brand. This will cover API Apps for mapping and rules and other such complexities.
A marketplace API app
In addition to API Apps you build yourself and ones Microsoft may build there is also the Azure Marketplace. The marketplace is a location in Azure where a vendor could publish their API App which they have created so that users of Azure can easily find API Apps that they may be interested in and can then add them to their setup and if required purchase them through the existing Azure procurement process they use such as an enterprise agreement or credit card billing.
Let’s pretend a vendor identifies that there is a gap where customers who build logic app want to be able to integrate into the Workdays SaaS application. The vendor may build an API App as a connector for Workdays and then go through the Azure Marketplace processes to be accredited and to be able to sell their new connector on Azure.
As a customer I may find their API App in the marketplace and decide that I need a connector for Workdays so I could add their API App which would be deployed to my App Service hosting environment and then I would be able to consume it from my Logic App.
Community API Apps
In addition to the marketplace another option would be for community developers to create an API App and then publish it on something like GitHub as an open source project. I could then get their community project and deploy the API App to my App Service environment and use the API App just like any other open source project I might use. As an example the Logic Apps team at Microsoft have already published a number of sample API Apps on GitHub on the below link:
At this point I hope that you can see clearly the different target use cases for the most common ways we will use API Apps and APIM. The below diagram provides a simplified view of the different core use cases.
Although there are some key target use cases where the 2 features could be used in isolation there is also a key use case where the two API features could be used together. This use case would be where you create your own API component using the API Apps template and allow it to expose a Swagger interface. You would then deploy it as an API App to get the hosting features from Azure App Service and then you would put APIM in front of your API component to provide the rich management features. In this case you would be using Microsoft’s best place to host your API component and Microsoft’s best API Management tool together to give you a rich experience as an API provider.
At present the only use case around combining API Apps and APIM is around this custom API scenario. From a strategic perspective however it would make sense for Microsoft to offer customers the chance to combine APIM with other types of API Apps you might use. APIM security and monitoring features could provide a rich addition to things like the out of the box API App connectors and BizTalk Integration API Apps to allow them to be even more powerful. Also as an integration architect I like the idea of APIM as a central repository or catalogue where I can see the usage of all API’s my organisation may be consuming and hopefully minimise the potential of stealth API usage or API spaghetti creeping in.
For Microsoft the APIM offering has been around for a couple of years now but the API Apps is relatively new and has yet to become generally available. I hope with this article I have helped to demystify some of the confusion around what each thing is and how they complement each other and what their differences are. I think at present the one biggest issue in this space is that the terminology around API Apps and the different flavours they come in can be a little confusing. I hope by GA there is a little more clarity in the naming’s used which makes this a little less confusing.
The thing that I really like in this space though is the opportunities to combine API Apps and API Management. The fact that they both use Swagger as a core technology within what they do makes the two API components strategically aligned quite nicely to be able to work well together and I hope to see Microsoft use this to their advantage as the products progress down their journey.