API Management Made Easy – The Undocumented API

API Management Made Easy

API-Management Azure API Management Preview is a service available in Microsoft’s cloud platform that provides an easy to use hosted Web environment to create a full featured developer portal for your RESTful Web API’s and produce rich analytics to gain insight into API usage. If you are building RESTful Web API’s as part of your employee or customer facing solutions, this is a must have service. In this article I will show you how easy it is to get started with API Management.


What is API Management?

Todays modern apps are built on a foundation of scalable cloud services and storage. A common architecture pattern for modern apps is to provide an application programmable interface, a.k.a. an API, to open up the functionality to more developers who then build client apps, mashups or provide integration between apps.

These Cloud Service API’s typically expose their endpoints via HTTP using REST (representational state transfer) protocol (GET, POST, PUT, DELETE) and are referred to as RESTful web API’s. By using this approach the implementation details of the API such as language, database, runtime, operating system, etc. are all abstracted. RESTful web API’s are by nature cross platform and can be consumed from any language, runtime, operating system, etc. that supports invoking HTTP requests.

It is rather easy today to build RESTful API’s in your language and platform of choice. Once you go down this path though it quickly becomes apparent you will need a great deal more infrastructure supporting your API’s in order to make them scalable, secure and are being used according to the usage and security policies that you define. This is where API Management comes into play.

An API Management system will wrap your API in its loving virtual arms and provide an additional layer of services. A typical set of services that an API Management system provides are:

  • Scalability
  • Security
  • Throttling
  • Trial-Mode
  • API Proxy
  • Policy Definition and Management
  • Developer Portal
  • Developer Registration
  • Developer Subscription
  • Developer API Key Generation
  • API Documentation
  • Monitoring
  • Analytics

You could develop these features on your own but doing so would add many months possibly years to your project. You have deadlines and can’t afford to be sidetracked designing, implementing and supporting app infrastructure. Just like your relational database, your source code control system, your developer IDE, API Management is something you purchase not build yourself. The feature list above is by no means exhaustive and so the scope of trying to build and maintain a system like this yourself hopefully is apparent and by leveraging a hosted pay-as-you-go approach to providing this app infrastructure you can easily make the business justification.

The Azure API Management service allows you to easily spin up an API Publisher Portal where you manage the various add-on services, generate API Proxies for your REST Services and spin up a Developer Portal where developers register and subscribe to your published API’s. By subscribing they receive a Developer API Key which they pass into every invocation of your API through the Proxy. The developer key is the lynchpin to the monitoring and analytics systems.


By adopting an API Management system that provides these turn-key services, you are able to manage the publication, promotion, developer registration and assignment of API keys, provide interactive documentation to developers, track usage and report on the health of your API in a matter of hours not months or years. These services provide you the foundation to harden your API and allow it to perform in mission critical situations.


Getting Started – The Unmanaged API

For purposes of this article, I will use one of my own REST services to demonstrate the process of adopting API Management.

The API that I am looking to manage is http://…/SFRestService.svc. This service provides access to CD and Track data from the Sounds Familiar Music Catalog. Sounds Familiar is my personal record label. In my copious spare time, I compose and record original music. I have also produced CDs for other musicians such as All Human Parts Orchestra.

This Web Service provides access to the meta-data for the available CDs and individual music tracks. By calling the API, a developer can access the list of CD’s with liner notes and cover art and the list of tracks for each CD. The track information provides the URL’s for the MP3’s for streaming purposes. The MP3s and album art are stored in Azure Blob Storage.

The Service was coded in C#, leverages WCF to expose the endpoints, returns JSON formatted data and is deployed in Azure as a Cloud Service. Note that your Web API need not be hosted in Azure or built using Microsoft technologies.

The base service can be called using these URL endpoints:




where the value at the end of the URL is a unique identifier for a particular CD.

A developer could create an app that provides access to this music catalog including streaming the MP3’s but I would not be aware of that usage other than a spike in traffic reported through the Azure Cloud Service Dashboard. If a great many developers started to use the API, my Azure usage could spike costing me $$ and I would not have any idea who was causing this to happen. There could be issues or feature requests and the developer community using the API would have no easy way to communicate and collaborate around the use of this now incredibly popular API. On one level a success story and on another a nightmare.

If I wrap the API using Azure API Management I would be able to control access to the API, monitor the traffic, health and get feedback from the developers to so that I could improve the service and increase customer satisfaction. To get started, I will need to create an instance of API Management in the Azure Portal.


Create an API Management Instance

Go to the Azure Portal (you will need a subscription) and click on API Management in the left hand menu:


Click the New button in the lower left hand corner and then select Create


API Management is currently in Beta and provides two pay-as-you-go pricing options. The Developer option will cost ~$50 a month and give you 166K API calls a day. Standard costs ~$350 a month and gives you 6.6M API calls day.


The Create process has two steps. First provide a name for your API Management Instance, your choice of pricing tier and where you want to host your instance. In the second step you set the organization name and administrator email.

image  image

Your typical Azure Dashboard is presented where you can get high level monitoring info, set the scale capacity for your instance and configure a custom domain if necessary. The real magic though is in the API Management Console. Click Manage in the tool bar at the bottom of the dashboard to navigate to the API Management Console.


The API Management Console

The API Management Console provides all the tools to configure API’s, view analytics reports, manage users (developers) and publish applications (apps that use your API’s) and also configure the developer portal, the place where users of your API will register, subscribe and learn about your API.


Add a New API

To get started click APIs and then Add API. Give your API a friendly name, provide the URL to the existing service and provide a top level name for the service that will appended on to the end of the new service URL. Click Save. This step will rename your cloud service and provide a new base URL for your operations.


Once you have defined your API, you will be presented with the Summary API screen where you will eventually see high level monitoring information and get access to the settings, operations and issues tabs.



The Settings tab is where you are going to start building up the documentation of you API by providing the Title and Description. You can also specify if authentication is required and modify the Web API URL suffix. For my managed API I chose catalog as the suffix.



On the Operations tab you define the service operations, build up the detailed documentation, activate the interactive API console, set operations limits, request/response validation and operation-level statistics.


The first step is to define the signature of the operation. In the example below I am exposing the /cds endpoint as a GET operation and then providing the documentation in the fields below. By doing this I have created a new signature for my CDS endpoint; https://soundsfamiliar.azure-api.net/catalog/cds.


If appropriate I can also setup caching and define parameters. This endpoint does not have any input parameters but our /tracks end points does. Lets take a look at that.

The /tracks operation requires a dynamic parameter, the unique identifier for the CD. To define the need for a parameter I will use the syntax {cdid} to represent the parameter. The URL template is set to /tracks/{cdid} on the Signature tab:



The details of the {cdid} parameter are defined on the Parameters screen. Note that you can provide a description, set the data type of the parameter and also define default and sample values. All of this information builds up the meta-data that provides documentation to developers on how to use your API. This will become apparent when we visit the auto-generated Developer Portal.


Now that we have defined our API, we will need to publish it. This is where Products comes in.


Define a Product

Our end goal of using API Management is that there will be a destination, a portal, where developers will go to register and then subscribe to a ‘Product’ that you are offering. Within a product there will be one or more API’s that developers will ‘Subscribe’ to. By subscribing they will receive an API Key which they must provide on each invocation of your API. This API key is the lynchpin of the system as it will provide the security, tracking and analytics for your API.

API Management defines two default Products:

  • Starter – Subscribers will be able to run 5 calls/minute up to a maximum of 100 calls/week.
  • Unlimited – Subscribers have completely unlimited access to the API. Administrator approval is required.

For purposes of this demonstration, lets define a new Product called ‘Public Product’. API’s listed as part of this product will be public API’s, no administrator approval required.

Click Add Product, provide the product name and description and click Save. On the Visibility Tab, check Developers. Once you have subscribers you will be able to see their information on the Subscribers tab.


Back on the Summary Tab, click Add APIs and add your API to this product.


Finally on the Summary tab click Publish to publish this Product. Developers will now be able to subscribe to your API on the Developer Portal.



The Developer Experience

In the upper right hand corner of the Administrators portal, you will see three links; Administrator (access your Admin profile page), Developer Portal and Sign out. Click Developer Portal. You will navigate to the auto-generated developer portal and be logged in as Administrator.

This is the site that you will use to promote your API’s giving developers the ability to register and subscribe. They will also be able to submit their apps which you can review and publish to the portal to help promote them as well. There is also an Issues page where developers can post issues they are having and you can provide support.


There is a built in CMS system available through the Administrators portal where you can modify the look and feel and provide additional UI components, pages and update the menu structure. This article will not cover the CMS system.

Developer Registration

When a developers arrives at your portal for the first time they will want to register. They will provide an email, a password, and first and last name.


Product Subscription

To access an API the developer will visit the Product page and click Subscribe.


Subscribing to a product will generate an API Key which they can access on their profile page


Using the api Console

Now that the developer has a key, they can use the API Console. They can click API’s and drill into specific operations and using their key, invoke the API’s to see how they function. Note that the information you entered in the Operations tab in the Administrators portal appears here as documentation.


The developer can also access auto-generated code samples on how to consume the API from a variety of popular languages.


The developer can click the HTTP GET button to see the results from the invocation. In this case well formed JSON is returned listing the CDs in the catalog. Note that the Request URL is shown and the developers API Key is appended to each call. I have blocked out the key below as that is my personal key.


Calling the Managed API from a Client App

Once subscribed a developer can add calls to your API from their applications using their API Key. Here is a code snippet from my Windows 8.1 Modern App called Sounds Familiar (what else could it possibly called?). Note the use of the managed version of the API and the addition of the API Key appended to each invocation. This code invokes the API, deserializes the JSON and maps the data into a View-Model that supports data-binding to XAML UI Controls.


Related Posts

Now that I have a client app that uses the API, I can submit it to the Developer Portal and if the Administrator approves the submission it will appear on the Applications tab of the Developer Portal.


Submitting an Application to the API Developer Portal

There is an option on a developers Profile Page to submit an app to the Developer Portal. The developer fills out the Application Submission form, uploads an icon and one or more screenshots and the link to the app.


The Administrator will see the submission on the Applications screen in the API Management console and can approve from this location.


Approved applications appear on the Published Applications tab and if drilled into a summary page is displayed.


Back in the Developer Portal, the app will appear on the Applications screen which will help promote it to other developers who use the portal.



Gaining Insight Through Analytics

Once there are apps using your managed API, your API Management instance will monitor and collect and data to be reported through the Analytics feature of the API Management Console.

The ‘At a glance’ page provides a Usage/Health chart that you can expand to cover different timelines and a tabular report that reports who is using the API’s and which operations are most popular. The Usage, Health and Activity tabs allow you to drill into specific API’s and operations and get more detailed information.

Using this information you can act on trends, understand how developers are using your APIs, visualize API performance, track error rates and the health in near real-time and act on those insights to deliver increased value.




If you are involved in the development of modern applications, designing and implementing service oriented architectures for the enterprise and are creating RESTful web API’s as part of your solution, you should consider using an API Management system. The Azure API Management service is feature rich and easy to use.

If you are interested in checking out my Developer Portal visit https://soundsfamiliar.portal.azure-api.net/, register and subscribe to the Public Product. You will then be able to invoke the Sounds Familiar Music Catalog API from the API Console.

If you want to check out the client app that uses this managed API download Sounds Familiar form the Windows Store.

– Bob Familiar, Practice Director, Cloud and Services, BlueMetal Architects


Additional Resources

Introducing Azure API Management

Josh Twist, Program Manager, Windows Azure, follow on Twitter @joshtwist

Azure API Management 101

Josh Twist, Program Manager, Windows Azure, follow on Twitter @joshtwist

API Management – Last-mile Security

Miao Jiang, PM on Microsoft Azure API Management, follow @miaojiang




4 observations on “API Management Made Easy
  1. Pingback: API Management Made Easy - Eat Sleep Code Repeat

  2. Pingback: RefM – A Microservice Case Study | The Undocumented APIThe Undocumented API

  3. Pingback: Internet of Things, A Reference Architecture | The Undocumented API

  4. Pingback: Lean Engineering – Lean Methodology Applied to Enterprise IT | The Undocumented API

Leave Your Observation

Your email address will not be published. Required fields are marked *

Read previous post:
Event: Make Your Field Staff More Productive – We’ll Show You How

  Do your employees in the field rely on a paper-based process to do their jobs?  Are they tied to...