In this article by Martin Abbott, Ashish Bhambhani, James Corbould, Gautam Gyanendra, Abhishek Kumar, and Mahindra Morar, authors of the book Robust Cloud Integration with Azure, we learn that it is important to know how to control and manage API assets that exist or are built as part of any enterprise development.

(For more resources related to this topic, see here.)

Typically, modern APIs are used to achieve one of the following two outcomes:

• First, to expose the on-premises line of business applications, such as Customer Relationship Management (CRM) or Enterprise Resource Planning (ERP) solutions to other applications that need to consume and interact with these enterprise assets both on-premises and in the cloud
• Second, to provide access to the API for commercial purposes to monetize access to the assets exposed by the API

The latter use case is important as it allows organizations to extend the use of their API investment, and it has led to what has become known as the API economy.

The API economy provides a mechanism to gain additional value from data contained within the organizational boundary whether that data exists in the cloud or on-premises.

When providing access to information via an API, two considerations are important:

• Compliance: This ensures that an access to the API and the use of the API meets requirements around internal or legal policies and procedures, and it provides reporting and auditing information
• Governance: This ensures the API is accessed and used only by those authorized to do so, and in a way, that is controlled and if necessary metered, and provides reporting and auditing information, which can be used, for example, to provide usage information for billing

In order to achieve this at scale in an organization, a tool is required that can be used to apply both compliance and governance structures to an exposed endpoint. This is required to ensure that the usage of the information behind that endpoint is limited only to those who should be allowed access and only in a way that meets the requirements and policies of the organization. This is where API Management plays a significant role.

There are two main types of tools that fit within the landscape that broadly fall under the banner of API Management:

• API Management: These tools provide the compliance and governance control required to ensure that the exposed API is used appropriately and data presented in the correct format. For example, a message may be received in the XML format, but the consuming service may need the data in the JSON format. They can also provide monitoring tools and access control that allows organizations to gain insight into the use of the API, perhaps with the view to charge a fee for access.
• API Gateway: These tools provide the same or similar level of management as normal API Management tools, but often include other functionality that allows some message mediation and message orchestration thereby allowing more complex interactions and business processes to be modeled, exposed, and governed.

Microsoft Azure API Management falls under the first category above whilst Logic Apps, provide the capabilities (and more) that API Gateways offer.

Another important aspect of providing management of APIs is creating documentation that can be used by consumers, so they know how to interact with and get the best out of the API.

For APIs, generally, it is not a case of build it and they will come, so some form of documentation that includes endpoint and operation information, along with sample code, can lead to greater uptake of usage of the API.

Azure API Management is currently offered in three tiers: Developer, Standard, and Premium. The details associated with these tiers at the time of writing are shown in the following table:

Key items of note in the table are Scale-out, multiregion deployment, and Azure Active Directory Integration.

• Scale-out: This defines how many instances, or units, of the API instance are possible; this is configured through the Azure Classic Portal
• Multi-region deployment: When using Premium tier, it is possible to deploy the API Management instance to many locations to provided geographically distributed load
• Azure Active Directory Integration: If an organization synchronizes an on-premises Active Directory domain to Azure, access to the API endpoints can be configured to use Azure Active Directory to provide same sign-on capabilities

The main use case for Premium tier is if an organization has many hundreds or even thousands of APIs they want to expose to developers, or in cases where scale and integration with line of business APIs is critical.

The anatomy of Azure API Management

To understand how to get the best out of an API, it is important to understand some terms that are used for APIs and within Azure API Management, and these are described here.

API and operations

An API provides an abstraction layer through an endpoint that allows interaction with entities or processes that would otherwise be difficult to consume.

Most API developers favor using a RESTful approach to API applications since this allows us easy understanding on how to work with the operations that the API exposes and provides scalability, modifiability, reliability, and performance. Representational State Transfer (REST) is an architectural style that was introduced by Roy Fielding in his doctoral thesis in 2000 (http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm).

Typically, modern APIs are exposed using HTTP since this makes it easier for different types of clients to interact with it, and this increased interoperability provides the greatest opportunity to offer additional value and greater adoption across different technology stacks.

When building an API, a set of methods or operations is exposed that a user can interact with in a predictable way. While RESTful services do not have to use HTTP as a transfer method, nearly all modern APIs do, since the HTTP standard is well known to most developers, and it is simple and straightforward to use. Since the operations are called via HTTP, a distinct endpoint or Unified Resource Identifier (URI) is required to ensure sufficient modularity of the API service.

When calling an endpoint, which may for example represent, an entity in a line of business system, HTTP verbs (GET, POST, PUT, and DELETE, for example) are used to provide a standard way of interacting with the object.

An example of how these verbs are used by a developer to interact with an entity is given in the following table:

When passing data to and receiving data from an API operation, the data needs to be encapsulated in a specific format. When services and entities were exposed through SOAP-based services, this data format was typically XML. For modern APIs, JavaScript Object Notation (JSON) has become the norm. JSON has become the format of choice since it has a smaller payload than XML and a smaller processing overhead, which suits the limited needs of mobile devices (often running on battery power). JavaScript (as the acronym JSON implies) also has good support for processing and generating JSON, and this suits developers, who can leverage existing toolsets and knowledge.

API operations should abstract small amounts of work to be efficient, and in order to provide scalability, they should be stateless, and they can be scaled independently. Furthermore, PUT and DELETE operations must be created that ensure consistent state regardless of how many times the specific operation is performed, this leads to the need of those operations being idempotent.

Idempotency describes an operation that when performed multiple times produces the same result on the object that is being operated on. This is an important concept in computing, particularly, where you cannot guarantee that an operation will only be performed once, such as with interactions over the Internet.

Another outcome of using a URI to expose entities is that the operation is easily modified and versioned because any new version can simply be made available on a different URI, and because HTTP is used as a transport mechanism, endpoint calls can be cached to provide better performance and HTTP Headers can be used to provide additional information, for example security.

By default, when an instance of API Management is provisioned, it has a single API already available named Echo API. This has the following operations:

• Creating resource
• Modifying resource
• Removing resource
• Retrieving header only
• Retrieving resource
• Retrieving resource (cached)

In order to get some understanding of how objects are connected, this API can be used, and some information is given in the next section.

Objects within API Management

Within Azure API Management, there are a number of key objects that help define a structure and provide the governance, compliance, and security artifacts required to get the best out of a deployed API, as shown in the following diagram:

As can be seen, the most important object is a PRODUCT. A product has a title and description and is used to define a set of APIs that are exposed to developers for consumption. They can be Open or Protected, with an Open product being publicly available and a Protected product requiring a subscription once published.

Groups provide a mechanism to organize the visibility of and access to the APIs within a product to the development community wishing to consume the exposed APIs. By default, a product has three standard groups that cannot be deleted:

• Administrators: Subscription administrators are included by default, and the members of this group manage API services instances, API creation, API policies, operations, and products
• Developers: The members of this group have authenticated access to the Developer Portal; they are the developers who have chosen to build applications that consume APIs exposed as a specific product
• Guests: Guests are able to browse products through the Developer Portal and examine documentation, and they have read-only access to information about the products

In addition to these built-in groups, it is possible to create new groups as required, including the use of groups within an Azure Active Directory tenant.

When a new instance of API Management is provisioned, it has the following two products already configured:

• Starter: This product limits subscribers to a maximum of five calls per minute up to a maximum of 100 calls per week
• Unlimited: This product has no limits on use, but subscribers can only use it with the administrator approval

Both of these products are protected, meaning that they need to be subscribed to and published. They can be used to help gain some understanding of how the objects within API Management interact.

These products are configured with a number of sample policies that can be used to provide a starting point.

Azure API Management policies

API Management policies are the mechanism used to provide governance structures around the API. They can define, for instance, the number of call requests allowed within a period, cross-origin resource sharing (CORS), or certificate authentication to a service backend.

Policies are defined using XML and can be stored in source control to provide active management.

Policies are discussed in greater detail later in the article.

Working with Azure API Management

Azure API Management is the outcome of the acquisition by Microsoft of Apiphany, and as such it has its own management interfaces. Therefore, it has a slightly different look and feel to the standard Azure Portal content.

The Developer and Publisher Portals are described in detail in this section, but first a new instance of API Management is required.

Once created and the provisioning in the Azure infrastructure can take some time, most interactions take place through the Developer and Publisher Portals.

Policies in Azure API Management

In order to provide control over interactions with Products or APIs in Azure API Management, policies are used. Policies make it possible to change the default behavior of an API in the Product, for example, to meet the governance needs of your company or Product, and are a series of statements executed sequentially on each request or response of an API. Three demo scenarios will provide a "taster" of this powerful feature of Azure API Management.

How to use Policies in Azure API Management

Policies are created and managed through the Publisher Portal.

The first step in policy creation is to determine at what scope the policy should be applied. Policies can be assigned to all Products, individual Products, the individual APIs associated with a Product, and finally the individual operations associated with an API.

Secure your API in Azure API Management

We have previously discussed how it is possible to organize APIs in Products with those products further refined through the use of Policies.

Access to and visibility of products is controlled through the use of Groups and developer subscriptions for those APIs requiring subscriptions.

In most enterprise scenarios where you are providing access to some line of business system on-premises, it is necessary to provide sufficient security on the API endpoint to ensure that the solution remains compliant.

There are a number of ways to achieve this level of security using Azure API Management, such as using certificates, Azure Active Directory, or extending the corporate network into Microsoft Azure using a Virtual Private Network (VPN), and creating a hybrid cloud solution.

Securing your API backend with Mutual Certificates

Certificate exchange allows Azure API Management and an API to create a trust boundary based on encryption that is well understood and easy to use.

In this scenario, because Azure API Management is communicating with an API that has been provided, a self-signed certificate is allowed as the key exchange for the certificate is via a trusted party.

For an in-depth discussion on how to configure Mutual Certificate authentication to secure your API, please refer to the Azure API Management documentation (https://azure.microsoft.com/en-us/documentation/articles/api-management-howto-mutual-certificates/).

Securing your API backend with Azure Active Directory

If an enterprise already uses Azure Active Directory to provide single or same sign-on to cloud-based services, for instance, on-premises Active Directory synchronization via ADConnect or DirSync, then this provides a good opportunity to leverage Azure Active Directory to provide a security and trust boundary to on-premises API solutions.

For an in-depth discussion on how to add Azure Active Directory to an API Management instance, please see the Azure API Management documentation (https://azure.microsoft.com/en-us/documentation/articles/api-management-howto-protect-backend-with-aad/).

VPN connection in Azure API Management

Another way of providing a security boundary between Azure API Management and the API is managing the creation of a virtual private network.

A VPN creates a tunnel between the corporate network edge and Azure, essentially creating a hybrid cloud solution. Azure API Management supports site-to-site VPNs, and these are created using the Classic Portal.

If an organization already has an ExpressRoute circuit provisioned, this can also be used to provide connectivity via private peering.

Because a VPN needs to communicate to on-premises assets, a number of firewall port exclusions need to be created to ensure the traffic can flow between the Azure API Management instance and the API endpoint.

Monitoring your API

Any application tool is only as good as the insight you can gain from the operation of the tool.

Azure API Management is no exception and provides a number of ways of getting information about how the APIs are being used and are performing.

Summary

API Management can be used to provide developer access to key information in your organization, information that could be sensitive, or that needs to be limited in use.

Through the use of Products, Policies, and Security, it is possible to ensure that firm control is maintained over the API estate.

The developer experience can be tailored to provide a virtual storefront to any APIs along with information and blogs to help drive deeper developer engagement.

Although not discussed in this article, it is also possible for developers to publish their own applications to the API Management instance for other developers to use.

Resources for Article:

Further resources on this subject:

• Creating Multitenant Applications in Azure [article]
• Building A Recommendation System with Azure [article]
• Putting Your Database at the Heart of Azure Solutions [article]