API management is a term that has been used in the API economy for several years and has existed without acquiring an exact, universal definition. While most protagonists in the API community agree on the core themes of API management and why the subject is important, the specifics are frequently defined by the capabilities of commercial “API management” solutions. The term has become so synonymous with these solutions that more than one have it engraved in their brand.

The tendency to align the definition of API management to a vendor solution is exacerbating the fact that the management of APIs is not generally discussed with a great deal of objectivity, as the subject is often skewed towards the vendor’s capabilities.

The dialectic on API management is therefore ripe for review. As the API economy continues to grow it is important that newcomers understand what API management is, why it is important, and how they should look to implement it. Past attempts to define the term have been done using surveys, cataloging the features of the most popular API management solutions available to organizations. Unfortunately, casting the net in this way obviously results in focusing on the solution rather than what API management should achieve: Looked at objectively, the features are an amalgam of other solutions and architectures, resembling SOA registries, Policy Enforcement Points (XACML), and so on.

Rather than representing the capabilities of a given toolset, API management is a generic practice that can be implemented regardless of any commercial solution an organization chooses to use. It is therefore important to arrive at a holistic and vendor neutral definition of what API management is.

A Definition of API Management

API management is the practice an organization implements to manage the APIs they expose. This is done either internally or externally to ensure that their APIs are consumable, secure, and available to consumers in conditions agreed upon in the APIs terms of use. Essential features API management should provide (rather than what specific solutions do) include the following:

• API management should provide a means for organizations to catalog their APIs, incorporating metadata such as the subject matter, description of the API (including different versions of the API that are currently available), human-friendly documentation, a taxonomy of the types of API available, and runtime capabilities (such as maximum requests per second). The catalog should also register the state of a given API, including metadata such as the currently supported versions;
• API management should also provide a means to act on the catalog, exposing the APIs therein to internal and/or external developer communities with the ability to enforce security controls, consumption entitlements (in the form of mechanisms such as rate limits or quotas) and surface multiple versions as required. The distance between an API being catalogued and it being exposed as a consumable endpoint should be as short as possible, with the transition being equally seamless;
• An organization may expose APIs here that do not meet the organization’s API “standards,” or exist in a form that an organization does not want to expose to their consumers (as it closely coupled an external exposed API to an internal system that is sensitive to changes). API management should also provide the ability to transform the inputs and outputs accordingly, exposing a standardized form to the API consumers;
• Finally, API management should be the system of record for API utilization, embellishing the catalog with information regarding the actual runtime behavior and characteristics of a given API in the form of metrics determined against key performance indicators. This information may include the number of API keys registered, average and peak requests per second, and so on: In fact, any data that is meaningful to the organization allows them to understand API utilization and plan accordingly for future enhancements or capacities. The information will also be used to help both monitor and monetize the APIs exposed, with the ability to make the data captured available to the organization’s operational or billing systems as required.

There are clearly other capabilities that API management solutions in the marketplace offer; for example, the ability to expose SOAP-based services and databases as RESTful endpoints, perform orchestration to such services, or directly monetize the organization’s APIs by billing consumers. While such features are clearly useful to many organizations who do not possess components in their architectures to perform these roles, we’ve deliberately kept them outside our core definition in order to center it on a set of features that all API providers need from their API management implementation.

The key point is that many organizations will look to leverage components they already have in their architecture for these capabilities, and duplicating them purely for their API offering is likely to increase complexity, in terms of both technology and process.

Components

Now that we’ve established a more concrete definition of API management, we can look at the components that make up the solution. In terms of the API management survey mentioned earlier, the components below are largely consistent with the majority of solutions found in the market at the time of writing and provide a convenient mechanism for grouping the features discussed in our definition. However, in terms of an architectural view, one should view these components logically rather than physically: All the components should be present in the logical architecture, but may be manifested in a different way depending on the API management solution.

In terms of an architecture, the components of API management are shown in the diagram below:

We’ll discuss the role of each in turn.

API Registry

As we discussed in the features section above, the key to effective API management is having an inventory of an organization’s APIs that allows API consumers to digest the characteristics of the APIs available, namely:

• Features: Describes what the API is designed to achieve in a form human beings can digest;
• Structures: A schematic description of the APIs, including URIs, data structures, security, etc.;
• Capabilities: What is the peak load the API can handle (both projected and actual) and the performance pinch points;
• Sensitivities: Does the API consume or expose any data that may be subject to regulatory or privacy constraint, such as payment card data, personally identifiable data, and so on.

The API registry provides this capability, holding data on behalf of the API Gateway and Developer Portal to provide a catalog of information for human beings to digest. The registry will also help an organization manage the lifecycle of an API, cataloging the supported versions and their promotion or retirement from the organization’s API inventory.

Going back to the point about logical vs. physical architectures, the API registry is the component that is likely to be manifested within other components in a physical architecture (most likely the Developer Portal), or indeed in many organizations may be federated across both API management and other systems in an organization’s stack. However, an idealist view of the API Registry is that this is a discrete component, specifically implemented to harbor an organization’s API knowledge.

API Gateway

If the API Registry is the brain of API management, the API Gateway is almost certainly the hands: It is where the business of API management happens as it is the component responsible for exposing the organization’s APIs to its consumers (which can of course be internal or external).

In brief, the API Gateway covers the following key areas (for a detailed discussion of the capabilities of the API Gateway please refer to our previous blog post on the subject.):

• Manifestation: Exposes the organization’s APIs to the outside world, acting like a proxy to route requests from external consumers to the API itself (as an aside, many API management solutions can also support backendless APIs, implementing the entirety of the API on the Gateway itself);
• Security: Acts as the gatekeeper to the API, applying security mechanisms on behalf of the API. Applying security at this outer perimeter is consistent with the cyber security principle of “defensive in depth” and is an important feature of the API Gateway’s capabilities;
• Entitlement: Allows access to APIs at the agreed upon rates and either limiting or managing traffic;
• Standardization: Presents a uniform suite of APIs to consumers (according to any API standards an organization might have);
• Logging and data capture: Captures the information required to understand API utilization, for a variety of purposes discussed below.

In order to expose, secure, and manage an organization’s APIs the API Gateway clearly needs to work in collaboration with the API Registry, ingesting information about the APIs and how they should be exposed. The API Gateway should also establish a feedback loop, supplying the API Registry with management-level statistics on API utilization, in order to help maintain an accurate picture of how the organizations APIs are used and thus their relative importance for future capacity and investment decisions. Finally, data captured by the API Gateway should be available for ingestion by any other system that requires it, for purposes such as monitoring, monetization, analytics or insight.

Developer Portal

The final component that forms our API management architecture is the Developer Portal. If the API Registry is the brain and the API Gateway is hands, the Developer Portal is the ears and mouth, where an API provider both listens and talks to the developer community. The Developer Portal provides the human interface to an organization’s APIs, providing a quality user experience (whether internal or external) and helpful tools and resources for building applications that consume the API. Moreover, the Portal provides the facilities for developers to manage their engagement with the organization.

To provide an effective management experience the Developer Portal should include the following features:

• Learning: Provides the facilities (documentation, how-tos, API descriptions, etc.) that a developer requires to understand the APIs on offer;
• Exploration: Delivers mechanisms that allow the developer to experiment with an organization’s API before they even write a stitch of code — interactive explorers, sample code generators, virtualization, and so on;
• Implementation: Helps the developer manage how their application(s) interacts with the API by providing the ability to register for a given price plan (if the API implements a charging model), create API keys and secrets, register callback addresses for OAuth, register webhooks, etc. (the specific features being dependent on the features of a given organization’s APIs);
• Feedback: Allowing developers to understand the metrics captured by the API gateway in the form of dashboards and insights. This can also be useful for internal stakeholders who will want to understand how the organization’s APIs are be utilized, for the purposes of operational monitoring or monetization (although the organization may choose to provide this information through existing tools rather than API management of course).

The Developer Portal therefore plays an important role in the overall developer experience, working in collaboration with both the API Registry and API Gateway to provide the information that developers need to correctly understand the organization’s APIs. It will also present usage data that helps API consumers understand how they are using the APIs, which can be important for improving their own applications or ensuring they are getting value from API consumption.

Final Thoughts

In this post we’ve attempted to set out a vendor neutral interpretation of API management. Clearly retrofitting a generalized framework for comprehending API management onto all the interpretations of the subject offered by solution vendors is going to be difficult. However, establishing the core principles of API management and what API management solutions should provide will hopefully help organizations who are implementing a practice of API management to apply objectivity to their view of what their requirements and needs really are, rather than simply adopting trends or feature-bloating on third party API management solutions.