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 .

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.

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 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.

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 chapter.