CodeGuru content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.

Introduction

Microsoft Windows Azure offers ‘API management’ to design APIs. This is a step towards designing the APIs first, even before actual implementation of APIs. This is something similar to what Apiary and other tools that are offered to design the APIs first and also generate documentation. Here, the creation of APIs are UI driven, where developers/designers can use the ‘API Management’ offering by using a Windows Azure subscription. In this article, we will see how ‘API management’ can be used to quickly design APIs.

Description

API Management gives a user friendly view to create or design APIs. Designing the API first approach builds the contract between the developers creating APIs and the developers consuming the APIs. Using this, the input parameters and the response is pre-defined to enable the developers and consumers work independently and more productively. In this article, we will see how to create your API design quickly.

To use ‘API Management’ in Azure, you need an Azure subscription to begin with. Once you log in to the Azure UI with your login account, navigate to ‘API Management’ and click “New”. Select API Management and click ‘Create’.

Figure 1: Creating a new Azure account

Specify a URL, select your subscription, and select a region. Then, click Next.

Figure 2: Selecting a subscription and region

In the next screen, enter a name and email address and then save the changes. This starts the process of creating an API service.

Figure 3: Entering a name and email address

Once the API is created successfully, select the API management service and click the ‘Manage’ button. this opens a new portal where APIs can be created and managed.

Figure 4: Selecting a management service

Clicking the Manage button brings up the screen where we can create APIs. This landing page provides options to create APIs and make these APIs available through products. It also allows you to define policies and the analytics; in other words, usage of the APIs and APIs that are used more commonly than others. In this article, we will elaborate more on creating API designs and publishing it by using ‘Products’.

Figure 5: The API Management Dashboard

Use ‘Add API’ to create a new API. In the API creation screen, mention the web API name, service URL, suffix, and then save the changes.

Figure 6: The API creation screen

Once the API is created, the next step is to add operations. To add operations to the API, click the API that was created and navigate to the ‘Operations’ tab. Then, click “Add Operation.”

Figure 7: Adding an operation

This brings up a screen where we can add operation details; for example, whether is a GET or POST method (HTTP verb), how the operation can be accessed; in other words, the URL template. In this example, we are passing two parameters to it. Specify a display name.

Figure 8: Adding operational details

Click “Parameters” and observe that the parameter mentioned in the URL template is automatically displayed on this screen.

Figure 9: The parameters screen

Add a description, type, and value to the parameters and then click “Add” under ‘Responses.’ This brings up a popup to select the response code. In this example, we select the ‘200 OK’ response.

Figure 10: Selecting the ‘200 OK’ response

Once ‘200 OK’ is selected, it opens a screen where a description and a response are represented.

Figure 11: The ‘Code 200 OK’ screen

Save the changes. Until this stage, we have designed the APIs. To verify these APIs, we can use the ‘Developer Portal’. Click ‘Developer Portal’ and, from the top menu, select ‘APIs’. This lists all the available APIs. Click the API that needs to be verified; this next screen displays the documentation of the API operation. In that screen, click ‘Open Console’ to verify the API. This also gives sample code to connect this API from various applications such as C#, Python, Ruby, and so forth.

Summary

Azure API Management is also a step in the direction where the API design happens first where the input and output parameters are defined and agreed upon first between the people developing and consuming the application. API design is mainly through the UI and the documentation is also generated for the same. This helps in creating a contract even before actual code is written.

Reference

http://azure.microsoft.com/en-in/documentation/services/api-management/