2187-just_azure.svg

Microsoft Azure is currently evolving at a phenomenal pace. One of the services that was recently released is Azure API Management (APIM). This brings API Management capabilities into Azure, and is the result of the Microsoft acquisition of apiphany in 2013.

The digital world is fast becoming one where APIs are a key business enabler. Whilst there are some notable examples of companies basing their business on having an API (e.g. companies such as Twilio), most businesses have some form of API that is used internally to support their business operations. Frequently these APIs are tightly locked down, but are APIs that could be exposed publically, APIs that support mobile applications, or APIs that could be made more broadly available within your organisation. Sharing these APIs can open up new possibilities for your business and even create new potential business models. Within an organisation, opening up these APIs may allow you to remove manual workflows to bring reduced overhead and a greater ability to respond to changes. For APIs available to partners or the public you may open up revenue streams by charging for the use of your API. Or maybe you use your API to increase your sales and the developer takes a cut of the sales made through their use of your API.

So what are the challenges that you might face? A common example is protecting your API through the use of API keys. You may want to control these and only grant them internally or to close partners, or you may want to make it easy for developers to sign up for them.

If you rely internally on an API that you plan to share more broadly then you may want to safeguard your usage of it by limiting the number, or rate of calls, from other consumers. Once consumers of the API have keys you will want the ability to view the usage of your API by those consumers. For example, if you’re driving a freemium model where developers can sign up for a limited quota for free but then pay for a larger quota the analytics can help drive increased revenue.

In short, whilst there are many ways to drive business value by making APIs available, there can be some challenges with doing so. It is these challenges that APIM sets out to address and we will look at how you can tackle them with APIM in the coming articles. In the remainder of this article we will take a quick tour of some of the key concepts with APIM.

Getting to know APIM

There are a number of different parts to APIM: the proxy, the management portal and the developer portal. These are outlined in the diagram below.

2206-AAPI-01-Fig1.png

Figure 1: An overview of Azure API Management

The Proxy

The proxy is where the API execution happens and where it is exposed to the callers. When the proxy receives a request it can re-map the URL and forward it on to your back-end API, as well as add caching and transform the result if you desire.

The backend API can be hosted in Azure or on-premises, and you can use mutual certificate authentication to provide additional security (for example to prevent a man-in-the-middle attack). It is likely that APIM will support VPN and/or Hybrid Connections in the future which would give more connectivity options to choose from.

The management portal

The management portal is the control room for you as an API owner. To start with, you can use the management portal to create and edit APIs. It is also where you configure how the APIs should behave and control who has access to call them. Additionally, you can view the analytics for the usage and performance of your APIs, and customise the look and feel of the developer portal so that it ties in better with your main site.

The developer portal

The developer portal is used to help developers to get up to speed with your APIs. When you create an API in the management portal you enter metadata about the API operations/endpoints. This metadata describes the shape of the API (i.e. the URLs), the HTTP methods that can be used, and the shape of the requests and responses. Using this metadata the developer API renders help pages for your API to enable developers to get started quickly.

When you publish an API it is common to think about how you can minimise the Time to First Successful Call (TTFSC). The documentation clearly helps with this, and to help reduce the TTFSC APIM also provides automatically generated samples in a number of languages (at the time of writing these are JavaScript, C#, PHP, Python, Ruby, Curl, Java and Objective-C).

Another feature that strives to reduce the TTFSC is the interactive console. This allows a developer to test the behaviour of the API directly in their browser. It prompts for the values to use for URL parameters and automatically adds the developer key in the subscription-key parameter – see the screenshot of the console below.

2206-AAPI-01-Fig2.png

Figure 2: Simple Echo API example

As an aside: whilst the interactive console passes the subscription key via a query string parameter, it is also possible to specify it via the “ocp-apim-subscription-key” header if that works better for your scenario

One other thing you may note in the interactive console is the ocp-apim-trace header. When you set this header (either from the console, or separately), APIM will enable tracing. In the response from APIM there will be an “ocp-apim-trace-location” header. The value of this header is the location of the trace output for that request. As you can see in the screenshot below, the trace is actually stored in Azure Blob Storage but APIM manages the details for this for you.

2206-AAPI-01-Fig3.png

Figure 3: Trace output

The trace output lets you see the stages that the request went through: the inbound request details, calls to the back-end API and any transformations that were applied by the proxy. All-in-all, this can be a very handy feature when you are debugging your API.

Wrapping up

That’s all for now – in the coming articles we will take a look at how APIM can help us to address some of the challenges we’ve identified. If you can’t wait for that then feel free to sign up for a free trial and start exploring APIM !

Thanks to Josh Twist (Principal Program Manager Lead for Azure API Management) for reviewing this article.