In the previous chapters, we have discussed what integration is in the new world of cloud computing and taken a look at how we can start building these integrations through the use of an Azure App Service plan and API Apps.
In order to understand how this applies more readily to an enterprise, it is important to know how to control and manage API assets that exist or are built as part of any enterprise development.
Typically, modern APIs are used to achieve one of the following two outcomes:
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:
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:
Microsoft Azure API Management falls under the first category above whilst Logic Apps, which are described in detail in subsequent chapters, when combined with Azure API Management provides 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:
Developer |
Standard |
Premium | |
API Calls (per unit) |
32 K / day ( ~1 M / month ) |
7 M / day ( ~217 M / month ) |
32 M / day ( ~1 B / month ) |
Data Transfer (per unit) |
161 MB / day ( ~5 GB / month ) |
32 GB / day ( ~1 TB / month ) |
161 GB / day ( ~5 TB / month ) |
Cache |
10 MB |
1 GB |
5 GB |
Scale-out |
N/A |
4 units |
Unlimited |
SLA |
N/A |
99.9% |
99.95% |
Multi-Region Deployment |
N/A |
N/A |
Yes |
Azure Active Directory Integration |
Unlimited user accounts |
N/A |
Unlimited user accounts |
VPN |
Yes |
N/A |
Yes |
Key items of note in the table are Scale-out, Multi-Region Deployment, and Azure Active Directory Integration.
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.
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.
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:
TYPE |
GET |
POST |
PUT |
DELETE |
Collection |
Retrieve a list of entities and their URIs |
Create a new entity in the collection |
Replace (update) a collection |
Delete the entire collection |
Entity |
Retrieve a specific entity and its information usually in a particular data format |
Create a new entity in the collection, not generally used |
Replace (update) an entity in the collection, or if it does not exist, create it |
Delete a specific entity from a collection |
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:
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.
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 API that are exposed to DEVELOPER for consumption. They can be open or protected, with an open product being publicly available and a protected product requiring a subscription once published.
GROUP provides a mechanism to organize the visibility of and access to the API within a PRODUCT to the development community wishing to consume the exposed API. By default, a product has three standard groups that cannot be deleted:
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, which is discussed later in the chapter.
When a new instance of API Management is provisioned, it has the following two products already configured:
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.
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 chapter.