Getting Started with Azure API Management

Introduction

It’s great to see how the evolution is taking place in IT world, mostly focused on sharing the existing resources leading to invent of cloud computing where resources are shared and used as a service on demand. Based on the type of resource shared, categorization is done – IAAS, PAAS, SAAS, IPAAS, FAAS etc. Off course, sharing is not free – you pay for whatever you use based on the charges defined per unit as to how long it is used and how much (time and amount). This ultimately helps in reducing time to market (by using already existing resource of others) and monetizing from the available resource (by sharing it).

Publishing the API (functionality) is just another thing on the same line – where the intention is to share a piece of function for enabling faster integration with clients or for monetizing from it.

API (Application Programming interface) is a set of functions/methods/procedure with a set of defined rules enabling the interaction between systems, applications, tools etc. Every organization has some or the other API (functionality) which can be used by others. It sounds great to share the capability, but with the increase in number of shared resources, two challenges also needs to be addressed – Security and Governance.

What is Azure APIM?

To cater the need around managing the APIs, Microsoft came up with a management solution i.e. Azure APIM. It is a Paas offering where you pay based on the tier(set of capacity features) you opt for.

Microsoft says - API Management (APIM) helps organizations publish APIs to external, partner, and internal developers to unlock the potential of their data and services. Businesses everywhere are looking to extend their operations as a digital platform, creating new channels, finding new customers and driving deeper engagement with existing ones. API Management provides the core competencies to ensure a successful API program through developer engagement, business insights, analytics, security, and protection. You can use Azure API Management to take any backend and launch a full-fledged API program based on it.

In Layman term - It is a layer (Proxy) behind which the actual APIs are configured, the proxy url are exposed whereas the actual API's url is mapped to it, along with some middleware capabilities like transformation, with an interface to consolidate and manage thousands of API’s across multiple platforms, an authentication and access control mechanism to manage and ensure security on API access and to monitor health of APIs, identifying errors, configure throttling, rate limits, caching mechanism and also provides insight into the utilization of APIs.

Building blocks of APIM

1. API Gateway (Proxy)

When you create an instance of APIM , you are asked to provide name to URL – it is here where the proxy gets created. So whatever APIs you create, import and want to expose are to go through this (the backend api url is mapped in settings). You can also choose to have custom domain mapped to this url.

Thus the Request is received here and it is here where you do all the pre-processing required on the request before handing over it to backend (the actual API).

2. Management (Publisher) Portal

It is an interface provided to you (publisher) to manage your API’s and to do the required groundwork before making it available to the consumers (internal or external). Earlier there was dedicated portal for it but now it is getting migrated to Azure portal itself (at the time of writing only Analytics was remaining to be migrated).

Below are the few things you can do (high level) –

· Create API, Edit API, Import API, Export API, Delete API, Add revision, Add version ,Clone API

· You can configure how the APIs should behave and control who has access to call them

· Import Operation, delete operation, clone operation

· Add Product, Delete Product, Publish and Unpublish Product, Add APIs to Product, remove APIs from product

· Store constant string values in NamedValue (properties collection of key/value pairs) which can be used in policy statements.

· Add Group, Delete Group

· Add Users, Delete Users

· Add certificates (can be used for validation in policy statement)

· Configuring the APIM instance itself through Settings section

· Configure Alerts, Application Insight using Monitoring section

· Add, Edit, Remove Policies

· Test the APIs before Publishing

· You can view the analytics for the usage and performance of your APIs

· Customize the look and feel of the developer portal

3.Developer (Consumer) Portal

It is an interface provided for consumers (users who are interested in using the APIs published by you).Consumers can be internal to your organization (say some other team, department) or your partners, clients etc. It is a placeholder of all the published APIs and Products (collection of APIs) which consumers can view or use (after they signup and subscribe).

You(publisher) can add static content, such as API documentation and terms-of-use, as well as dynamic content such as blogs and forums.As an API provider, you need a way to expose your APIs, educate developers about your APIs, sign up developers, and let developers register apps. Also you can change the look and feel of the developer portal (it is HTML based).

4. Products

It is through Product, APIs are made available to consumer. A Product can have one or many APIs. It is actually logical grouping of APIs which share common policies or are from same business process etc. Before using any API from any Product, the consumer needs to subscribe to that particular product and in return consumer gets Subscription key upon administrator’s approval or auto approved (based on approval configured in setting). So whenever consumer needs to invoke the API, it needs to pass on subscription key in header, else will encounter Access denied due to missing subscription key error

Products are of two type – Open and Protected. Open (public) Products are the one which doesn’t need subscription and protected ones needs subscription. By default there are two products available when you create a APIM instance – Starter and Unlimited (both are Protected). You can create Product as per your requirement.

5.Groups

Level of access (view, consume, read, write etc.) of Product is through groups. Based on the requirement users can be added to respective groups – Administrator (users can perform all actions), Developer (users can consume the APIs) , Guest (users can only view), this three are out of box groups made available. But new groups can be created and users can be added to them. Users can sign up using developer portal or can be created by or invited by Administrator.

6. Policies

Policies are the real meat, it is through it APIM becomes powerful offering various capabilities. Using policies (set of statements) you can define the behavior of your APIs, basically providing governance around them. It is basically a XML document with mandatory sequential sections in it (inbound, backend, outbound), defining the order in which policies are executed.

Inbound section – For applying policies at entry point itself, like from where it can be called, how many times it can be called, validating the certificate etc. (Restriction, access, authorization etc)

Backend section – For applying policies before calling backend, like replacing some elements in request, converting from xml to json etc (enriching the request message, complying to expected format by backend etc)

Outbound section – For applying policies at exit point, before sending response to the caller, like setting http status code, xml/json to json/xml etc.

There is one more section, on-error which can be added. It basically acts as a catch section for above all section. If anything goes wrong in any of the section, only then on-error section comes into execution else not(provided you have added it). It is an exception handling mechanism provided out of box.

</inbound>

<!-statements to be applied before the request is forwarded to the backend service go here -->

</backend>

</outbound>

<on-error>

</on-error>

</policies>

Each of the section can have none or many statements within it. Statements are the policy (feature/function) which can be added in appropriate section based on the functionality needed. For now statements are categorized as following (based on purpose they serve)

1. Access Restriction Policies

2. Advanced Policies

3. Authentication Policies

4. Caching Policies

5. Cross domain Policies

6. Transformation Policies

There are actually four scopes/ wherein policies can be applied

1. Global scope (to all products)

2. Product Scope

3. API Scope

4. Operation/method scope

All statements are not available or not valid at each level, few only make sense at product level whereas few only at operation level, thus in policy editor sometimes you might see some statements are greyed out. There are scenarios where a statement applies or is required at more than one level – in that case there is provision to avoid duplicity and simply inherit the statement from parent scope using <base/> element. Also if you want certain policies of current scope to be applied before parent level policies then just change the sequence as followed -

</inbound>

</policies>

Although the default behavior is to execute parent level policies first, but with use of <base/> element and changing the sequence of it, the order can be changed.In any level where you use base element, at runtime that is replaced with the statements of the parent level. There are situations where only statement is not enough, in that case there is provision to use expressions within statement.

Note: <base/> element is not allowed in global scope, as it is the top most level thus no parent scope to inherit from

If you worked with BizTalk, concept of policies to me reminds of pipelines (which are used for preprocessing and post processing of messages).

How it works

The publisher creates an API or imports already existing API, adds it to existing Product or creates new Product and adds the API, publishes the product. Publisher then shares the developer portal url to the consumers.

The consumer signups using developer portal if not already already added/invited by admin. Consumer then subscribes to Product and gets the subscription key (if protected Product), also goes through the API documentation to understand the method supported and message format/content type.

Consumer sends a request to the APIM Url (gateway/proxy) with subscription and content type as a header, APIM engine then loads the policies. Policies are actually a XML based configuration file which has elements/statements/functions in sequence denoting the order in which their execution is to be performed.

How is security designed?

In APIM following things are taken into consideration from security perspective – preventing unauthorized access, preventing excessive usage, preventing content attack etc. The very first thing is subscription, it has a primary and secondary key and one of these needs to be passed in the header of the request to the APIM thus enforcing pre access check. Also there is provision in security settings to go with OAuth 2.0 or OpenID Connect which forces consumers to supply a valid authorization token in the request header. Mutual Certificates can be used to limits access to your Backend API by sharing a certificate between APIM and your Backend API. APIM can also be deployed in Virtual Network.

Read about using APIM for securing apps -- Securing Logic app with Azure APIM

How to check happenings in and around API?

Analytics - insight on the usage/health of the APIM artifacts like which Product/api is receiving more request ,from where we are getting more traffic or to see the response time of particular API etc.

Activity Log - insight log of actions taken on the artifacts of APIM activities, like if you want to know when a particular product was created, when was it deleted etc. It is actually subscription level perspective log.

Diagnotics Logs - insight log of actions taken by the artifacts of APIM. It is resource level log which captures actions that were performed within that resource itself, like when operation was called etc

Metrics - It is in built set of query to show real time happening around the APIM, like number of total request came in, number of failed request etc.

Alerts - You can setup notification based on the metrics and logs, sending an email to statekholders or you can also automate a process by using logic app by triggering it with alert.

Apart from above there is also provision to enable Application Insights to capture the telemetry data also there is provision to surface the above logs to OMS

Good to have

1. One thing which I think would be great to have is Intellisense in Policy editor :) .
2. Provision to enable/disable the APIM instance