Summary
In this article, the third in my series on internet scale architecture, I will discuss API management. This covers the design, documentation and implementation of web APIs and their runtime deployment in a secure and scalable fashion. It also includes aspects such as monetising APIs as well as usage and performance reporting. The previous instalments in this series are an introduction to internet scale architecture and a discussion of edge services.
Introduction
Years ago, I helped operate a B2B platform. We exposed an enterprise service to external consumers via a variety of mechanisms, including SOAP web services, EDIFACT over AS/2 and even via sFTP. I know this must sound unbelievably barbaric to readers of the 21st century, but it is true, nonetheless.
The process for onboarding new consumers was roughly like this: we received an email from a developer in the consuming enterprise saying “Hi, I’m Fred Foobar from Acme corporation, can you send me the URL for your test environment and give me some credentials to test with? Oh, and can you send me some interface docs, please?” If you guessed that we didn’t have more than a hundred consumers, you would be right.
Now, if you want to operate at internet scale, you’re not only going to have to deal with the runtime scalability of the platform, but you will also have to scale the operational aspects of your platform, which includes solving issues like these:
- How do I efficiently onboard new consumers?
- How do I make it easy for them to use the platform?
- How do I give them access tokens, so they can access the services that I have authorised them to access?
The short answer to all of these: you need an API management platform!
API management platform capabilities
First, here are some examples of API management platforms:
- Apigee (Google)
- 3-Scale (Redhat)
- Mulesoft API Manager
- TIBCO
- Microsoft APIM
- AWS API Manager
Generally speaking, an API management platform offers the following capabilities:
- API gateways – components that proxy traffic from consumers to services that implement APIs. Traffic can be checked for appropriate authorisation, throttled and have transformation performed on message payloads before being sent to the back-end service.
- Developer portal – a web portal for developers to view documentation on your APIs, download SDKs to develop with, register their applications and request access to secure APIs
- API life cycle management – to manage the development, deployment, publishing and versioning of APIs
- API analytics – to receive real-time data about the performance and usage of your APIs
- API monetisation – to manage service plans, billing and charging for the use of your APIs
Most API management platforms provide the above-mentioned capabilities as Software as a Service (SaaS). However, some allow on-premises deployments or hybrid models in which some components, especially API gateways, run on the premises, with the rest of the components running as SaaS. Apigee is a good example of this.
API management platform example
A good example of an API management platform that I am familiar with is Apigee, which has been acquired by Google.
Figure 1: Apigee overview
As a prominent example of an API management platform, I will explain Apigee’s main components in a bit more detail below.
API proxy
These runtime artefacts are deployed to Apigee API gateways and are responsible for proxying requests from consumers to back-end services. Their rules are defined in an XML format to execute policies in a pipeline or flow at either the proxy endpoint, which encapsulates entry to the proxy, or at the target endpoint, which encapsulates access to the back-end service. The proxy and target endpoints are separated to allow us to include policies to operate on the requests and responses as both flow from the client to the endpoint. Here is an example of a flow for the proxy endpoint:
Figure 2: Proxy endpoint flow
The green box shows the different policies that have been defined. We are also shown a PreFlow for the proxy endpoint (highlighted in blue). Finally, the red box shows the policies that are applied in this flow: one to verify an API key and another to return a cached API response if available. The proxy definition is available in XML source form so that it can be stored in a source code repository.
Figure 3: Target endpoint flow
For the target endpoint, the blue box shows the URL of the back-end service that implements the API, in this case a simple mock service. The red box shows the application of a ResponseCache policy to cache the result of the service call.
Overall, there are more than 30 policies that can be applied in categories like traffic management, security, mediation and extension.
API products
API products are a key concept in Apigee. They are collections of API proxies, including API resource paths on the proxies and access rights, with a quota of service calls that may be made. This construct allows us to build service plans, for example free tiers that allow a limited number of service calls and then various paid tiers permitting more frequent access depending on how much the consumer is willing to pay.
Let’s assume that I have an e-commerce site selling widgets, for which I have proxies for widgets that maintain the vehicle information, including an online catalogue and orders to view, submit, update and cancel orders. I might create an Orders_bronze product that has
- widgets API proxy with / catalogue resource with READ access,
- orders API proxy with / resource with READ, WRITE access,
- quota of 5 API calls per second
whilst an Orders_gold product used by a major broker would have
- widgets API proxy with / catalogue resource with READ access,
- orders API proxy with / resource with READ, WRITE access,
- quota of 1000 API calls per second.
Apps
An app is a collection of API products with credentials for each product. These are intended for consumers of the APIs managed by the platform. If a developer wants to use one or more API products, they can request access via the API management platform. If the request is successful, they are granted the necessary API secrets or access tokens. You’ll want to make this process as simple and automated as possible, especially if you have internet scale numbers of consumers.
Many API management platforms support monetising your APIs. This means they allow you to take payment from a prospective user for the use of higher-tier API products (like the Orders_gold product in the example above). This is done when the user creates an app, which includes relevant API products and often involves the user supplying credit card information to allow charges to be levied for the use of the API.
Developer portals
Apigee allows administrators to build one or more developer portals to publish documentation on APIs via markdown and through API specs. Many developer portals also offer sandbox testing environments for consumers to test their API clients. Examples of great developer portals (not necessarily Apigee ones) can be found at devportalawards.org.
Conclusion
We explored how apps make it easy and scalable for consumers to obtain credentials for our services and how developer portals facilitate easy access to quality API documentation and testing infrastructure. We also encountered the benefits of having your API gateway running in an elastically scalable SaaS. All in all, I hope this short tour through the features of Apigee has helped further your understanding of how an API management solution addresses the challenges of managing APIs at internet scale.