API Management - Towards a Reference Architecture

In one of my previous posts, I extolled over the virtues of opening up APIs over the web so that others can use them. A prerequisite for doing this was that an API management tool (a new breed of middleware) had been deployed. Although I gave a short - architectural- overview of what an API management system should comprise, I stopped short of giving a full reference architecture. My reason for this was that I couldn't find one - especially one that was vendor neutral (and a good reference architecture should be).

Not to be thwarted, I've set about creating one. Now creating reference architectures is tough and creating one for a relatively new topic such as API management is even tougher. So you should consider this post as a beta version for two reasons:

• As the field matures we will see a better understanding of what is really considered as API management.
• In my mind some important elements of a reference architecture are missing (better said, they haven’t been done - yet); elements such as the architectural principles, design patterns used and different viewpoints.

The reference architecture described here then, is mainly functional with some structural elements, i.e.:

As the reference architecture doesn’t exist in isolation, it is separated into three contexts:

• The consumers of the APIs
• The API Management itself
• The provider systems that the API Management interfaces with.

The API management itself is split into three main areas, each of which has a number of elements. The elements form a typical set of functions that API management vendors provide. Of course, some vendors provide more.

The Gateway provides the actual API to the outside world, typically as a REST like interface. Consumers are usually applications developed by end users or by other providers who are aggregating functionality (e.g. as mash-ups). Typical elements are:

Translation is often provided to translate internal application interfaces to something that can be used as a web API. Often, this is a translation between SOAP/XML and REST/JSON, but it can also provide facilities to translate data fields or filter the functionality provided by the internal interface so only a subset is available to external consumers.

Licence Key Authentication. Prospective consumers of an API usually need to first register - typically over the developer portal. After this they are provided with a licence key which they have to provide with each call of the API. This component checks the validity of the key and causes the gateway to refuse the request if it was not valid.

Throttling restricts the volume of calls that are made to the API from a particular licensee. For instance, a prospective consumer may have a obtained a free developer licence that allows to the API to be called only once a second. A “production” licence key could allows a higher volume of calls, but has a price tag.

Access Control usually works in conjunction with the provider's identity management systems to control access to the internal API using the identity information provided by the consumer application.

The Management subsystem forms the central management of the API. As such, it is usually the provider’s staff who use this. Typical elements are:

Licence Key Management is used to generate licence keys and determine the policies associated with them. If API usage is payed for by the consumers this also typically maintains who has licences and the licence type. This information is used later for billing.

API Meta-Data Repository contains all the information describing the APIs, i.e. their interfaces and data schema as well as policies associated with them This data is maintained by the provider, but made available to prospective consumers over the developer portal.

Life Cycle Management handles the complete lifecycle of the API: its creation, publication, versioning, deprecation and eventual retirement.

Billing monitors the usage of the API that is used for billing the consumers. It usually interfaces with the provider's own financial systems.

Analytics are typically provided to give information on how the API is being used.

The Developer Portal is a website that allows developers to find out what APIs exist, their details (driven from the information in the API Meta-Data Repository) and also their status (driven from the life cycle management).

Another essential function of the developer portal is for developers to obtain licence keys that they can insert into their own applications.

The developer portal can also provide:

• “How to” information to get a developer quickly up to speed in integrating the API with their applications.
• Means to try out the APIs.
• Social aspects such as comments and forums. 
• Publishing API details to public sites such as programmable web.

As I mentioned, API Management is an evolving field. If you think that some functionality is essential and I haven’t included it, please tell me.