How to use Azure API management to make your life easier

One of the most exciting evolutions on the web today is the ever increasing number of publicly available APIs as exposed by companies and individuals. These APIs allow their owners to expose data from internal systems to the Internet so external developers can begin playing with them. Websites such as ProgrammableWeb list all those APIs, and the list is growing every day.

What all this means is that, instead of creating an application that leverages your data or services, you simply publish an API, and let other people create applications. Or, you could do both. Facebook, Twitter and Google, for example, all have their own applications, but publish their services and data to APIs too.

Creating such an API is one thing, the other thing is to publish, maintain, and document it. You probably don’t want everybody to have unlimited access to your developments – you might want to have a documentation site with examples and you may also, quite naturally, want to monetize it.

Now here’s the good news: the Azure Management API does all of this, and more! It allows you to publish your API to the Internet, automatically generate code samples and documentation, configure access & throttling, analyze usage of your API, and more.

What are we going to show?

In this blog post, we will publish an internal data source to the cloud by creating an API, published to Azure Management API. This involves the following steps:

1. Create a Web API
2. Publish this Web API to an Azure web app
3. Publish to Azure Management API
4. Use it in a client project

Create a Web API that publishes data

In today’s post I’ll be creating an ASP.NET Web API project in order to publish a fictitious data-source. This might be an internal database, for example test results, or analysis data, or whatever. For simplicity’s sake, I’m not going to publish a real data source, but create stubs to simulate a data source. In either case, the steps to take are exactly the same.

I’m going to be publishing our fictional data source to Azure as this is the easiest solution. Feel free to follow along – you’ll need a (free) active Azure subscription. Alternatively, you could deploy it to any IIS website, as long as it is available to the Internet.

So, stretch your muscles, crack your fingers and let’s get down to business!

Start off by opening Visual Studio. I’m using Visual Studio 2015, but this should also work in different versions. Click File -> New Project and choose Visual C# -> Web -> ASP.NET Web Application.

Enter a useful name and location, and click OK.

In the next screen you can pick a template. I’m using the Web API template in ASP.NET 4.5.2, and command it to host in Azure:

Also, click on Change Authentication and set it to No Authentication:

Click OK in this screen, and on OK in the New Project screen. In the Azure pop up, you need to enter the details of the Azure Web App. I’ve decided to create a new Azure Web App in Australia East:

Click OK, and your project will be created. This may take a minute, so grab a cup of coffee so you’re ready to go for the next bit!

The default Web API template contains a lot of stuff, most of which we won’t need. But I want to focus on the Azure API Management side, so I’m not going to clean up the project.

The default template contains one ApiController, called ValueController. Hit F5 and navigate to /api/values. You should see the two test values:

In your production API you probably don’t want to begin by using this template, and I’d advise you to start from scratch and only add the things you need. But in our case this default template will work fine.

A Web API service is a RESTFUL service. A downside of this is that you get no machine-readable definition. Azure API Management will require a Swagger or WADL definition. By default this is not available, so I’m going to add this now by adding Swashbuckle. Open NuGet Package Manager, search for Swashbuckle and add Swashbuckle.Net45 to your project:

Click F5, and navigate to /swagger to see this:

Let’s create our Azure Management API

Before Azure can manage our API, we need to publish it to Azure. Right-click the API project and select Publish:

You can leave all the default settings as they are, and click Publish. Wait, wait, wait, and your browser should open and show your public website! Woop woop!

Now, browse to /swagger, and copy the documentation URL to your clipboard or notepad. In my case, it was this URL: http://azureapidemo0955.azurewebsites.net:80/swagger/docs/v1

Next, go to the “old” Azure Portal (manage.windowsazure.com), as this functionality is not available in the new preview portal (portal.azure.com). Click on New -> App Services -> API Management -> Create:

Pick a name, subscription, a region and hit Next:

In the next screen you need to enter contact details:

We don’t need to set Advanced Settings, as the default settings (e.g. developer price tier) suffice. Hit the checkmark to Complete.

You probably want to go do something else for a while, as this may take up to 30 minutes. Grab a bite to eat maybe and come back once you’re done!

Manage the Azure API Management Service

When provisioning is ready, select it (don’t click on the title!) and click Manage in the footer. This will open the Azure API Management Portal.

Click on Import API, select “From URL” and enter the details:

I’ve added the API to the “Unlimited” products group. For some reason, I received the error:

“Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API” when testing from the API Portal, as that header was not pre-populated then. Hit Save, and click on Developer Portal in the header:

What you see now, is the public developer portal of your own API! This is the starting point for anyone using your API. People can read documentation, test your API, and sign up to use it.

Click on API -> Azure API Demo -> Values_Get - GET 1 to test the GetAll method. Hit Send and see the magic happen. The Azure API Portal calls your Web API and shows the following result:

We have now set up the basics. The API is managed by Azure API Management, there is a developer portal where users can sign in, and more.

Leverage the protected API from our MVC controller

I’m going to show that I can consume the API from the project created earlier and implement throttling. First, add the product “Starter” to the API. From the Azure API Management Portal, click on APIs -> AzureApiDemo -> Products and add Starter.

Next, go to the Developer Portal and click on Administrator -> Profile. Copy the Primary Key for the Starter Subscription:

Copy this value to notepad.

Our Web API project also contained an MVC part that renders the documentation. I’m going to add some code to display that we can call the API, managed by Azure API Management.

Next, open Controllers -> HomeController and replace the Index method with the following:

Replace the subscription key with what you copied earlier.

Last, add @ViewBag.WebResponse somewhere to the View in Views -> Home -> Index.cshtml

If you now hit F5, you will see the response from the Web API, via the Azure Management API Service.

But, when I refresh the browser 6 times, I’ll get an exception:

This is just the beginning

In today’s post what I hope I’ve shown is how you can publish an API to Azure Management API, and protect its usage with usage throttling. But that’s just the beginning - there is so much more that can be done. Here’s a few additional features you should definitely look at:

 1.      Statistics

From the Developer Portal, click Administrator -> Manage

This will bring you to the Analytics view in the Management Portal with a wide range of analytics data.

2. Products

We briefly touched on this by adding our API to the Product “Unlimited” and “Starter”. A product defines who can use it, and how often. For example, the default group “Starter” allows users to run up to 5 calls/minute with a maximum of 100/week.

See the Microsoft site for more information.

3. Connect to internal API’s with Azure Direct Connect

In my example, I’ve published the API to a public Azure Web App. In most cases your API resides on your internal network. With Azure ExpressRoute you can make your API available to Azure Management API via VPN. Your API will still be hidden from the outside world, only Azure can access it. See here for more information.

I’d also suggest you check the Advanced Documentation on the Azure site for even more awesome examples.

All being well, you’ll have learnt how to publish an API to a public Azure Web App today, and had at least one cup of coffee and a light lunch. Get in touch in the comments section below and share your thoughts!

Want to build your desktop, mobile or web applications with high-performance controls? Download Ultimate Free trial now and see what it can do for you!