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:
- 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
- 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 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 XML format, but the consuming service may need the data in 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, 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.
- 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.
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 .
Note
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.
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:
- Administrators: Subscription administrators are included by default, and the members of this group manage API service 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, which is discussed later in the chapter.
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's 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.
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.