API management solves the problem of handling the scale of API adoption within an enterprise. In their earlier avatar, most API management tools were solely used for monitoring and granting the API access. However, with standardization efforts around OAS (OpenAPI Specifications), it is now possible to capture all API lifecycle stages in a well-defined specification and enforce them in a unified manner across all APIs.
This post was originally published in Rakuten RapidAPI
Depending on the strategic intent of a company in leveraging APIs, the role and responsibility of an API Platform may also vary. Smaller companies opt for open source API management tools with some standard management features but limited by customization options. Large companies, having a well defined, ecosystem driven API strategy, would prefer a platform with additional features for fine-grained control over every aspect of API governance.
This is the dilemma of the API Ops team or the CTO of a company when they are tasked with selecting or upgrading the platform. This blog post will guide you to understand the reference technology stack of an API management suite. It will dissect the “behind the scenes” components that make up a feature-rich API management platform. The knowledge gained from understanding the technology stack will eventually empower you to make the best decision for spearheading an enterprise-wide API strategy in the best interest of your company.
Component of an API Management Platform
In the true OSI reference model fashion, let’s define a generalized stack for the API management platform.
The OSI Layer Equivalent of API Management Stack
Starting from the bottom, the chief responsibilities of each of the layers are as follows:
- 1Gateway Layer: This is the bottom-most layer of the stack. It houses the API and its business logic. This layer also manages the underlying computing and memory resources for executing the API business logic.
- 2Interface Layer: This layer manages the mappings and protocol conversion between the actual API resources defined in the gateway and the custom endpoints exposed to the outside world for accessing the API. In this way, it hides the internal API implementation from the external world and provides secured access to trigger the API.
- 3Analytics Layer: This layer is responsible for handling the API metering and keeps a tab on the API related usage stats. It also monitors the vital parameters for assessing the health of APIs.
- 4Policy Layer: This layer is the key to enforce access rules for all interactions between the API and the users. At the heart of this layer is a policy-based framework for defining rules and constraints based on API parameters. In some ways, this layer is like a nerve center of the API management platform and wields an indirect control over all other layers for defining and enforcing policies.
- 5Access Layer: This layer is responsible for managing the users and associated logical groupings that define an API user persona. The most common forms of these groupings are roles and teams. Additionally, this layer manages the workflows that govern the API interactions with the different personas such as the API consumer, API producer, and the API manager.
- 6Lifecycle Layer: This layer defines the internal states and properties of the API workflows corresponding to the lifecycle phases. It also manages the state transitions across the three broad life cycle phases of an APIs life, namely publishing, governing, and consumption.
- 7Application Layer: This is the topmost layer. It defines the application-specific content templates and the presentation logic for the user to discover, search, and access APIs. It also houses secondary applications for managing the API artifacts such as specifications, documentation, and tutorials or hosting API issue tracking systems.
Layer wise Feature Lowdown
Let’s take a deep dive at each of the layers to understand their functionality. However, instead of getting into the technical details, our focus will be on describing the features of an API management platform influenced by each layer.
With this approach, you will understand how every layer augments an API management platform with specific features. Additionally, it will help you build up a set of compliance checklists for your API management requirements.
Gateway Layer: The API hosting service
Logically speaking, the gateway layer is not a part of API management. This layer hosts the actual APIs, which are under the purview of API management. Therefore most API management platforms do not provide this layer as an integral component of their system. Either this is an ad-on subsystem or an external API gateway.
Here are the main features of the gateway layer, or an API gateway (if integrated as an external system)
- Configuration options for defining the API specifications, including the URL resource structure, methods, request and response templates, protocols, for the API.
- A programming environment for developing the business logic for API.
- Computing and memory resources for executing the API business logic.
- Mechanisms for traffic policing, in the form of rate limiting, quotas, DDOS protection.
- API staging and sandbox environments for testing and simulation.
Historically, API backends have been built using application servers and deployed via Apache or Nginx web servers. Most programming language ecosystems such as Java, PHP Ruby, and Python have many application server frameworks to choose from. However, many are built on monolithic architecture.
If you are looking to host APIs at scale, it is better to build the business logic on containerized platforms such as Docker with microservices architecture. It makes the API hosting infrastructure very elastic, which is easy to grow and shrink with the hits on API.
For complex business logic involving computationally intensive tasks, some API gateways also provide a service mesh architecture. This approach enables internal invocations between various microservices that host the API to reuse the business logic.
At a super scale, where you have to deal with hundreds of containers every second to handle API calls, it is better to use a container orchestration service. Kubernetes and Apache Mesos are the most preferred orchestration platforms available for you. Both bring their unique strengths, but the detail of the pros and cons is a discussion for another topic.
Interface Layer: The glue between API management and API
The interface layer is technically the lowest layer that plays a role in API management. Most often, it is the interface layer that has to be tweaked to make the API management platform work with an external API gateway.
This layer always gets involved as part of publishing a new API, when the API’s public URL needs to be channeled to its internal hosting environment.
The most important API management features contributed by the interface layer include
- Maintaining URL mappings between the API and its associated hosting environment.
- Providing secured access to API hosting environments to avoid direct break-in by external entities.
- Supporting plugins and extensions for enabling custom API behavior, request or response modification, data transformation, and custom error handlers.
As far as managing the mappings with the gateway layer is concerned, the innards of this layer are less complicated than other layers. However, special attention must be taken for security when integrating with external API gateways.
For plugins and extensions, some API management platforms provide preset libraries to choose from. In case you want more flexibility, you have to opt for an extension framework that allows a developer interface to build your custom plugins in the programming language of your choice. These plugins can be registered to trigger during API invocations to perform specialized functions, such as protocol conversion.
Analytics Layer: The custodian of API metrics
With so many APIs being managed by the platform, tracking their performances individually is a significant challenge. Hence the need for an analytics layer is a no brainer, especially when it comes to monetizing your APIs.
Here are the key traits of a good analytics layer
- A mechanism for capturing and reporting API usage, performance, and health metrics.
- Ability to segment and aggregate API monitoring statistics based on users and teams.
- Tracking the billing for APIs.
- Ability to raise alerts and send notifications based on certain thresholds getting breached by specific API metrics.
There is no end to the kind of analytics that can be done on APIs. However, most API Ops engineers and API managers are interested in the daily/weekly monitoring of APIs only. Additionally, this layer may also act as a gatekeeper for restricting API access if certain metrics have crossed a threshold limit. As an example, if your API strategy demands setting a usage quota for each API, then the quota checks will be enforced in this layer.
If you have such special requirements, you must check out the API management platform’s documentation for setting alerts and notifications based on API metrics. Also, many platforms offer advanced segmentation and predictive analytics features that make the API Ops team’s life a bit easier in managing day-to-day chores and suspicious activities related to API usage.
Policy Layer: The nerve center of API governance
As we mentioned before, the policy layer controls the configurations for all the other layers. It aligns with the API strategy of an organization and influences how anyone deploys, configures, and uses the APIs. It enforces constraints on all operations to be performed on APIs.
There are diverse ways in which we can define these policies. Every platform has its way of achieving this through a large category of policy definition parameters. These parameters identify users, API properties, status codes, events, and more. There are always preset policies that are available. Additionally, a policy definition language allows administrators to define and enforce custom policies.
Internally, this layer consists of a rules engine for maintaining the policy definitions. This component and a policy control mechanism are used to enforce the policies for all operations performed via the API management platform.
Access Layer: The gatekeeper for API access
A human user uses every API. There are many ways to represent a set of users. The user is coupled with a set of workflows to achieve the desired outcome for interacting with an API. This layer manages the user-centric aspects and the workflows for accessing the APIs explicitly.
The layer can augment the capabilities of an API management platform with some features such as:
- User, role, and team definitions.
- Advanced user aggregations to define departments, as well as external stakeholders such as customers, partners, suppliers.
- Various authentication and authorization mechanisms to control access to the APIs.
- Visibility control of APIs.
- Custom workflows to consuming APIs.
Life cycle Layer: The guardian of API’s life
This layer manages the life cycle stages and transitions for APIs. This function is important and works in conjunction with the policy layer to ensure that the APIs follow a well-defined life cycle progression.
The importance of this layer can be realized when managing a continually changing API to support
- Administrative transitions of life cycle phases for the API.
- API versioning.
- Gracefully retiring the API (also applicable for initially cradling the API.)
- Marking the API with special status (such as deprecated or disabled.)
- Setting tags, properties, or other metadata to APIs for better discovery or policy enforcement.
Internally, this layer would be typically realized as a state machine and a lookup table.
The state machine maintains the current life cycle phase of each API as a state and enforces the pre-conditions for state transitions. The lookup table stores and fetches the associated properties that are added to the API.
Application Layer: The API playground for users
The application layer provides for the user experience of API users, chiefly the API consumers. However, it also serves the API producers and the API Ops to administer the APIs. This layer is supported by a backend web server hosting to deploy a web-based portal.
An API management platform may choose to have a single hosting for all the three personas or deploy separate partitions of the layer as three different portal applications.
The critical features contributed by this layer for an API management platform are:
- Portal application for accessing APIs.
- Multiple UI templates and themes for the portal.
- API information presentation formats along with documentation, testing console, tutorial library, and discussion forums.
- Admin dashboard for API Ops team.
- API Configuration console for API producers.
- API search, discovery, and user engagement groups for API consumers.
- Ability to store and display API metadata such as Open API specification definition, tutorials, and sample codes, files, and other artifacts.
The above are the standard features found on most API management platforms. However, there are many more proprietary options to enhance the user experience of API management applications.
The design of the application layer is a key influencer in building a thriving API ecosystem. One of the major impediments in API adoption is the lack of flexibility to adopt external APIs at scale. With the increasing use of APIs, it is impractical to develop them internally, and integrating with third-party APIs is a laborious chore.
The Man-Machine Interface for API Management
Having covered all the features and functionalities of an API management platform through the layers, we come to the final piece of the puzzle.
How do the different API user personas interact with the stack?
Here is a more detailed view of the tech stack we presented earlier.
The Man Machine Interface to API Management Stack
In this case, the application layer has multiple planes of access for the API consumer, the API manager, and the API producer. The access mechanism for the API manager is special because of the need to administer the entire system.
The API consumer interacts with the application portal, which facilitates the discovery, subscription, and testing of API. Along with it, the portal, based on the features of the API management platform, also provides helpful information such as documentation and fosters an API ecosystem.
The API producer mostly accesses the gateway layer. This is where the deployment happens. Apart from that, there are multiple deployment options to support separate API versions, sandbox setups, and special configurations for auto-scaling.
Finally, as evident in the illustration, the policy layer has inherent control over all the layers. It acts as an intermediary between the API manager and the entire API management platform.
Its Decision Time
So if you are planning to invest in an API management platform for your company, then which features would you choose?
This is definitely a tall task. The realm of API management has grown over the years, so deciding the specs and selecting the features is a complex process. Moreover, it has to align with your organization-wide API strategy as well.
We hope that this post has cleared the cloud about the various moving parts and functions that constitute a complete API management suite. You should now have a good idea to ask the right questions and make a better evaluation of any API management platform vendor.
Let us know your thoughts on the comments below.