What Is Azure API Management ?

Azure API Management Service is a PaaS (Platform as a Service) offering by Azure. This service provides a secure way to publish and manage the APIs created by on-premise or cloud backend services. Azure APIM service acts as an intermediate layer between the backend applications that hold the code behind the API endpoints and the consumers of the API endpoints.

This platform as a service offering provides easy management of the APIs by way of many built-in policies that control requests and responses, built-in authentication methods, and monitoring capabilities.

Features of Azure API Management Service

• Auto-Scaling: Depending on the pricing tier for the APIM service, auto-scaling can be configured based on metrics.
• Managed and Self-Hosted Management of API Instances: You can use the Azure-handled management gateway portal or configure your management gateway portal so that your API backend and management gateway are hosted in the same infrastructure and region.
• Monitoring API: Continuous logs and metrics are available to monitor API outages, traffic bottlenecks, etc.
• Greater control over how inbound requests and outbound responses are handled using various built-in policies, e.g.: limit API requests in a given duration, restrict IPs, handle query parameters, etc.
• Multi-Region Deployment: APIM service instances are usually deployed in one primary region, but for the Premium pricing tier, API gateway instances can be spread across regions to provide improved latency.
• Security: API security provides the ability to integrate with Azure Entra ID, OAuth 2.0, Azure AD B2C, authentication certificates, etc.

To Know More about Azure API management service – Read.

Key Components of Azure APIM

Backend API

This is the API endpoint exposed by the app created and hosted using various other platforms. Eg. Say a web API app built using .NET Core and hosted on an on-premise server.

Basic flow of inbound request and outbound response in Azure APIM

API Gateway

This acts as an abstraction layer between the consumers of the API and the backend architecture of the API. With the API Gateway, complex details of how the API is developed, the code, the hosting details etc. is hidden. This makes it easier to perform other management and monitoring tasks of the API that do not need such added information. The API Gateway receives both inbound and outbound requests for the Backend API. Azure provides with an Azure managed API gateway that is associated to the API endpoints.

Azure also provides Managed and Self Hosted Gateways.

• Managed API Gateway: Handled and maintained by Azure.
• Self Hosted Gateway: A way to create and manage your own gateway. Here you spin up a container and host the gateway in a setup managed and operated by yourself. This could be an option if you need greater control for security , traffic to the endpoints, or want the API gateway to be in the same region of where your API is hosted.

Whichever is used, it is the gateway that handles the requests and responses along with integrating with Azure monitoring capabilities, it is responsible to relay log and metric information and fulfill policy requirements.

API Management Plane

Provides management capabilities to setup API endpoints, create API service instance, add or remove policies, provide templates to create different endpoints. Basically management plane provides administrative tools for API service management. The management plane also has a REST API endpoint, making it also possible to programmatically maanage and administer API management services via ARM templates, SDKs, PowerShell, Visual Studio etc.

Developer Portal

This is an auto-generated yet customizable website that displays all published APIs and documentation needed to use the APIs. The developer portal also provides a console to test the API endpoints from within it. It is a great management tool that lets developers login, subscribe or even guest users to use the available APIs.

Basic Building Blocks of Azure APIM Service

Products

Product is grouping of APIs that you want to publish like a package to consumers. When you publish a set of APIs as a product, you can

• control how APIs are accessed via subscription
• set approvals for accesses.
• set policies at product level, so the policy rules apply to all APIs in the product
• test the APIs in the Developer Portal Console

  

Subscriptions

Subscriptions are a way to access APIs securely using a subscription key. This subscription key is added to the header of a HTTP request using the key Ocp-Apim-Subscription-Key. The key can also be sent as a query parameter using name subscription-key. Subscriptions can be scoped at:

• All APIs
• Each API
• Products

As shown below, a built-in all-access subscription key is provided by Azure, that is scoped at the APIM instance level. Which means this key can be used for all APIs in the particular APIM service instance. Because this is an all-access key, it must be used only by authorized users.

These subscription keys can be regenerated, cancelled and also deleted.

Users and Groups

Users here means developers that you add or invite to use your published APIs. These users are not to be confused with users in Azure tenant. These users can be added to groups for better distinction and management.
Azure APIM service instance always comes with 3 built in groups – Administrator – This is a system managed group that has the administrator setup during APIM service creation as its only member.

• Developer – All users added, invited or those who sign up are added here. Any user by default gets added to the Developer group
• Guests – This is also a system managed group and lists unauthenticated users visiting the developer portal. You cannot manually add members to this group.
  

Policies

Policies are a set of instructions/rules in an XML based format that influence how inbound requests and outbound responses are processed. Azure APIM has certain built-in policies for e.g.: to allowing incoming requests from certain IP addresses or block requests, validate the request or response body against an API schema, check the query parameters in the request before passing it to the backend etc. Apart from built in policies, azure portal also provides a way to customize and configure your own set of policies. You can have multiple policies associated at once and they will run in the sequence of how they appear in the XML document. Policies can be scoped at different levels:

• single operation in an API
• All operations in an APIs
• Product
• Global – for all APIs
  
  

  Built in Inbound Policies for All APIs

  
  
  

  An XML view of an inbound policy having limited rate of calls applied to an API operation

Steps to Publish an API using API Management Service

For this demonstration, we will assume a scenario where a fictional company called Contoso has developed a set of APIs (users/todo lists), and employs Azure API Management Service to publish these APIs, thus making the API endpoints available to developers. We will be using the free API endpoint provider https://jsonplaceholder.typicode.com/, but you can use or create any API endpoint of your choice.

Step 1: Create and Configure an API Management Service Instance

Select the API Management Service from the Azure Portal.

Enter API Management Instance name, Administrator Email and select the Pricing Tier = Developer. The administrator email will be the credentials used as administrator for the developer portal. Let the rest of the information be as default. Click Review + Create

Step 2: Add API Endpoint for Users and ToDos

• Navigate to the demo-mockapi APIM service instance and click on APIs on the navigation blade. Here you see , that Azure provides a default EchoAPI. But we want to setup our own API, so we will add a new HTTP Endpoint.
  
• Setup an HTTP End Point like below. For this example, leave the API URL Suffix as blank. The API URL Suffix is the URL Path, and should be unique for every API. This acts as a distinguisher between different API paths.
  
• Now we have setup the API Endpoint but have not configured any information for the operations that the API allows. Navigate to the User ToDos API and select “Add Operation”
  
• Now we will map our API methods here. This acts as a frontend for the actual backend API. Enter the details as below to map the GET method. The “/users” indicates the resource that GET method retrieves.
  
• We can test this endpoint method , select the operation and click Test. This opens a portal, that where we send any request parameters, header key-values, values for url placeholders etc. i.e. whatever is needed to test the operation
  
• Response Body and response status is returned
  
• Repeating the above steps, we will now add a few more operations. Add an operation to Get user details based on a parameter passed. Define a default user id value in the Template Parameter section.
  
  
• Next, we will add an operation to get all ToDos.

  

• Next, add an operation to get all pending ToDos for an given user id
  

Step 3: Setup the Developer Portal

• First time Developer Portal is opened, it may take a while to setup. Later, any changes you make to the drag-and-drop component website, you need to publish the Developer Portal with every change. Here navigate to the Developer Portal through Azure APIM service instance.
  
• After the Developer Portal opens, make any changes to the website layout you want and click Publish Website. Whenever you open the Developer Portal from Azure, it will open in an edit mode by default.
  

Step 4: Add developers as Users

• In order to simulate a scenario to show how developers will be able to access the published APIs of DemoCompany, we will create fictitious user in API Management service instance. Note that, be default all users are created with status = Active and assigned to the Developer Group. Navigate to Users and click Add button. Set up the details of the developer (use a valid email address).
  
• Once added, you see the list of users as below. As of now, there will the admin user and the developer user.
  
• Also navigate to Groups, to have a look at the 3 built-in user groups namely Administrator, Developer and Guests as discussed before.
  
• Click the Developers group, to confirm if developer John Milton has been auto added
  

Step 5: Create and Configure Products

• From navigation blade select Products and click Add button.
• Let’s call this product Premium , Check “Published” and “Requires Subscription”. Add User ToDos API to the product.
  
• Navigate to the Premium product. Select Access Control and Click Add Group button
  
• Add the Developers group so that members of the developers group now have access to the Premium product.
  
• An overview of the Premium product, gives all the necessary information
  
  

  Premium product Overview

Step 6: Create Subscription for the Product

• Because we setup the Premium product to have subscription mandatory, as subscription key is created at the scope of the product. Navigate to the Premium Product and click Subscription.
  
• We will use this autogenerated subscription key for consuming the APIs

Step 7: View the Published APIs via Developer Portal

• Sign In to the Developer Portal using credentials setup for our developer John Milton.
  
• Navigate to the Products. Select the Premium Product
  
  

  List of Products accessible

• Select the User ToDos API and now you see the list of operations we setup.
  

Step 8: Test the User ToDos API

• To test the Get Users operation (or any operation of your choice), we could use any API testing tool or service like Postman API etc. Ensure that authentication is Basic, and the request header, contains subscription information as shown below.

  
  

• Here is the response of Get Users operation of User ToDos API.
  
  

  Get Users Response

Azure API Management – FAQ’s

What are the allowed options for the backend API host, in order to integrate with Azure APIM?

The advantage of Azure APIM lies in its ability to provide complete abstraction and separation layer to the complexities of the backend API strategy. Hence, any API hosted on premise , or other cloud provides, or any Azure service like Azure Functions, Azure Logic Apps, Containers, Microservices, Azure Web API etc.

How to enable a blanket policy for all APIs in line with an organization’s compliance requirements?

While Azure provides built in Policies covering a whole lot of frequently needed rules on request and responses, it is also possible to customize these policies. Additionally, Policy Fragments is another way , where one can create a custom reusable XML based policy that can be included in any other policy document.

How are policies evaluated if multiple are applied?

If there are multiple policies, then evaluation is done sequentially

Is it possible for Developer Portal URL to contain organisation domain name ?

Yes. Be default the developer portal URL and gateway URL uses the *.azure-api.net subdomain. One can configure a custom domain for gateway and/or developer portal to point to company name. The URL would then look like for eg: demo-mockapi.developer.mycompany.com

How to prevent guest or anonymous access to the developer portal ?

Subscription Key based approach is good approach to limit unwanted access. However, if it is a strict requirement to allow access to developer portal only to registered users, then one workaround is to force the Sign In page so anonymous users and login or sign up to use the developer portal. Select Identities from Navigation Blade of API service instance -> Click Settings -> Check Redirect anonymous users to sign-in page. Now all users that arrive at the Developer Portal will need to sign in/sign up.