Azure API Management and Azure Mobile Services

 

Azure Mobile Services simplifies the creation of scalable REST APIs. Now, with the release of Azure API Management, you can complement your API with state of the art API management capabilities.

In this blog post I am going to show you how you can use Azure API Management to manage your Azure Mobile Services API.

 

But wait… What is API management anyway?

 

Let’s assume you have a unique dataset that you want to expose for development consumption via a REST API. In doing this, you’ll certainly consider in your solution key design aspects such as scalability and developer friendly operations. Cool! But now let’s think what other considerations you need to take into account so you can provide the best experience to your customers –i.e. developers.

For instance, creating an online presence for your API that allows the developers to request access to your API, which also includes developer documentation with samples from a variety of programming languages as well as the necessary information to become the main hub of communications and information between you (the API owner) and your customers (developers using your API), is certainly something key to consider.

As an API owner you want to manage the developers that are using your API, including tasks such as grating or revoking access or even extending invitations to your API. As an overall concern you want to protect your back-end by imposing rate limits for some scenarios. Furthermore you might want to create API offerings with different limits for test or preview scenarios and others less restrictive for production or paid customers.

In terms of maintenance, you’ll benefit from API monitoring so you can gain insights into how your users are calling your API and also have visibility into errors to help you pin point issues. And chances are, that from these insights you’ll identify the need to implement a caching approach for some of your operations.

Well, sounds like lots of work, right? And indeed it is, but fortunately with Azure API Management you can easily implement these features and way more!

 

Let’s create a manageable API

 

With Azure Mobile Services you can create scalable and robust APIs very quickly. What I am going to show you next is how, just as easily you can use Azure API Management to enhance your Azure Mobile Service API with the following features:

  • API Developer Portal with API documentation, testing capabilities and code samples.
  • Two API products with different rate limits and access policies.

 

As an example I will be using the to-do list API with full text search that I discussed in a previous blog post

 

1.- So let’s create an instance of Azure API Management in the Azure Portal and add our Azure Mobile Service endpoint.

image

Note: There are two pricing tiers for Azure API Management: Developer and Standard. For pricing details here.

 

Once your service is available, you need to go to the Management Console.

 

image

 

Once there, we will add our Azure Mobile Service endpoint, by clicking on the Add API link.

 

image

Next, we need to configure the security settings so our API Management service can call our Azure Mobile Service API. To do this, click on Settings, and enter your Azure Mobile Service’s application key both as a username and password using basic authentication.

 

Note: You can get your application key in the Azure Portal, by going to the dashboard of your Azure Mobile Service and clicking on Manage Keys

 

image

 

2.- Next, we will add our API to a product.

A product in the context of your API Management service contains one or more operations from one or more APIs that developers can subscribe to. By default a new instance of Azure API Management has two products: Starter and Unlimited. The Starter product allows subscribers to make 5 calls per minute, up to 100 calls per month and doesn’t require approval. The Unlimited product allows unlimited calls and requires approval.

What makes this very cool is that without writing a single line of code from the same API you provide two offerings, one with limited access for testing or prototyping scenarios and another with restricted access but without limits and geared for production scenarios.

 

Note: You can further customize the products with different policies and rate limits as well as creating additional products.

To add our API to the Starter product, we need to click on Products on the left menu, and then click on the Starter product. 

 

image

 

Then click on Add API to Product and select your Azure Mobile Service API.

 

image

 

Finally, let’s perform the same procedure for the Unlimited product.

 

3.- Configure Azure Mobile Services API operations

At this point, we are ready to select the API operations we want to expose. To do this, click on your API, and then click on the Operations tab and finally click on Add Operation.

 

image

 

Before adding an operation there are few concepts that you need to be aware of.

First off, at a very high level you can think of the API Management service as a proxy that has the ability to rewrite the URL to call your source API. So you can use this feature to simplify requests by changing parameter names, providing constant values or shorten the URL. In the URL template you define the API’s client facing URL. The Rewrite URL template defines how your source API will receive the request from the API Management service. You can use values inside the braces –e.g. {id} – to define values that the API Management service will pass to the source API from the client.   

The following table shows the configuration values for the CRUD operations of the API as well as the custom search operation.

 

Note:  I am shortening the client facing URL and I am defining the same parameters as the Azure Mobile Service API. The parameters follow the OData protocol, for more information see Operations on a table, in the Azure Mobile Service REST API Reference.

 

image

 

After adding all these operations your API’s operations should look like as follows.

 

image

 

4.- The Developer Portal

The developer portal is the main point of entry for the developers. From there they can check API documentation, request access to the API, support and even forums! You can customize the developer portal with your own theme, style and content. 

 

Note: For more information about customizing your developer portal check Customizing the developer portal in Azure API Management.

 

To access the developer portal click on Developer Portal link in the Management Console.

 

image

 

And you can see your new shiny developer portal!

 

image

 

5.-  Code Samples and Testing your API.

Part of what makes the developer portal a powerful tool for managing your API is that automatically creates sample documentation on how to you call your managed API from a variety of programming languages. To check this feature click on the APIS tab in the developer portal and click on your API.

The portal shows all the operations that you configured with samples for various programming languages!

 

image

image

 

To test any operation click on it and then on the Open Console button. The following is an example that invokes the insert operation where I specify my subscription key, the content type header and the json representing my data.

 

image

 

And success!

image

 

Wrapping up!

 

We discussed the creation of API Management service in Azure and configure it to use Azure Mobile Service. We also reviewed some of the really cool features of the developer portal including code samples and the ability to test our API.


9 Comments

  •  sam
          Commented

    I tried adding my mobile services key in the username and password , but i keep getting 401

    Reply
    •       Commented

      Hi Sam - Thanks for your comment. Please make sure that the permissions of your table operations are set to "Anybody with the Application Key"

      Reply
      •  sam
              Commented

        I'm using a custom api and my permissions are set to any body with a key. Where in the MSDN documentation does it mention to put the set the application key in the username and password field of the api management settings? thanks

        Reply
  •  sam
          Commented

    Also, tried with a table operation and same 401..

    Reply
    •       Commented

      Hi Sam - If you are using JavaScript as the backend, you need to send your app key in the X-ZUMO-APPLICATION http header. You can do this by sending this header in your request to the endpoint protected by the API management instance or by creating a custom policy that performs this for you.

      Reply
      •  sam
              Commented

        I was thinking as much (as I am using the Node js backend), I'll give it a go tomorrow and let you know how I got on.. Thanks alot

        Reply
        •  sam
                Commented

          yep, that was the one.. I just added the required application key to the incoming http header in the policy and everything worked.. thanks alot

          Reply
  •       Commented

    I am taking out API Management for a test drive. I have created a WCF Service with one operation called ping. First question. MUST I decorate the Method with [WebInvoke] to make it work in Azure API Management? IE, does what Azure connects to must be REST or can it be plain WCF?

    Thanks
    Ralph

    Reply

Post Reply