API-Management 101

API-Management and the 'API economy' is the a hot topic at the moment. Many customers have heard about it and seen the flurry of products that have been introduced into the market in recent years. However, when speaking with customers, it's clear to me that many are not clear on exactly what all the elements are that make up API-Management. This can lead to customers not understanding the architecture and sometimes the benefits of API-Management for their business. Here I'll break down API Management into its constituent parts and try to help you see why you might want them in your business.

A lot of this confusion comes around because API-Management is not one single thing. It's a host of small functions and advantages. Some of those functions have previously been called other things or have been hidden from the business guys by the architects who didn't need to expose the function to the business level. Let's go through them one-by-one...

API

Let's start with the obvious - what is an API? An API is just that - an 'Application Programming Interface' - just the same way it has been for years in many different guises. The difference here is that we're not talking about say, a Java class's interface, but an interface into a hosted service that is (probably) in your enterprise as shown below.

Don't let the word 'service' make you think that this is just Web Services either. Today, API's are nearly always WebServices (SOAP) or REST (I've not seen anything else!) and when the interface is a REST interface the data format is nearly always JSON.. However, this does not mean that the back-end service that you are exposing has to be outputting SOAP or JSON; you may have a current service that outputs SOAP (or anything else !) but you want to expose to the world the same content in JSON using a REST interface. You may also want to expose a single 'API' that is actually a conglomeration of different back-end services that's made to look like a single API to the users of the API. The job of the API-Manager is to do this exposing of a single viewpoint of your back-end systems to the world.

Although, I'm going to discuss exposing API's from a back-end system to external customers (business partners or clients) they can also be internal API's. For example services made available from one group in your business to another .

Security

A key job of the API-Manager is to secure the API being exposed. After all, APIs are usually exposed through the DMZ and are exposing back-end services to the world. There are several elements to that security, these include the usual: authentication (who wants to use the API) and authorisation (can someone use the API). When discussing API-Management the normal methods for enabling these elements of security are either HTTP Basic auth, OAuth or OpenId (and I'm not going to go into the difference between OAuth and OpenId here as it appears to be becoming a religious debate ;-). 

There are several varieties and flavours of OAuth and I'm not going to touch on these here. Because  the internet is trying to become more security conscious all the time it is getting more and more normal to use OAuth rather than just HTTP Basic Auth when securing API's. However, Basic Auth does allow you to get up and running just a little easier in dev and test environments.

With this security comes key management which are integral to the OAuth specifications (and of course username/password management with Basic Auth). API Managers have the capability to handle these keys with such things as creation and refreshing of keys being standard.

Denial Of Service

Denial of Service (DOS) attacks are clearly a risk in this sort of environment. You are not only exposing your crown jewels to the world but also advertising the fact ! Most API-Managers have some kind of DOS attack defence mechanisms built-in but those that don't appear to be adding it in as customers are beginning to demand it.

Caching

A general function that many gateway servers encompass is caching of the content that they are serving. API-Managers are no exception however, given that the data flowing may be changing quite rapidly it may be that the caching capabilities are limited just by the style of data being served.

Usage Tracking

As with any system the business would like to know whose actually making use of the API's. This is also the job of the API-Manager. Again, common function is evolving here: some vendors not only track the usage in the API-Manager but also allow you to view those usage statistics from within the API-Manager interface. Others just keep track of the usage and then farm out the pretty graphical tools to third party tooling. I suspect that, over time, we'll see most API-Managers having built-in tooling for viewing usage statistics.

Usage Throttling

Complimentary to usage tracking and Denial of Service attacks is usage throttling. API-Managers have built-in function that allows the API administrator to specify levels of usage of the API. 

The usual analogy here is of the gold, silver and bronze users. Where the Gold users can, say, get unlimited access to an API versus the bronze who can only access an API, say, once every minute. Once those usage limits have been reached it is the job of the API-Manager to block the user until such times as the time limit has run-out. There are subtleties to these algorithms. For instance, only allowing bronze users in during certain times of the day. Or, perhaps if the system is looking overloaded, allow gold users through before allowing silver and bronze users. 

All of these parameters are configurable to different extents on different vendor's platforms. Although not all vendors offer the same range of function at the moment they are all trying to achieve the same overall goal - that of controlling how much an API can be used.

Monetisation

You may well have heard of the 'API Economy'. This encompasses the idea that APIs can also be charged for (along with many other connotations but I'll just discuss the technical angle here). 

This goes hand-in-hand with Usage Tracking and Throttling. Once we have have the functions of usage tracking and throttling it is not a large step to add in the ability to charge and invoice users. At this point in time most vendors have, at the very least, some kind of ability to output the gathered usage statistics to an external customer invoicing process. As API managers evolve I expect this function to be enabled more and more within the API-Manager itself.

API Store

Once an API is defined it's an obvious thing to want to advertise it. Most vendors have supplied an integral API store in their solution. This store functions as a single shop-front to allow developers to view and sign-up for APIs. Documentation of the API can also be exposed in the store. The function of the store also often includes the ability for social media interactions; things like voting on APIs; in-built forums for the specific APIs; commenting etc.

One of the key things that stores enable is the ability for what's called self-registration. Imagine that your API is the most popular API in the company and that you have hundreds of users wanting to sign-up and use it. You don't want to sit there all day accepting requests to access your API ! So, stores allow you to build rules to automatically allow certain classes of users to access your API (whether that be 'everyone' or just some specific group).

Sandbox

APIs are often evolving beasts and to this end you may have one version in production and another in development. This brings with it the the age-old problem of version control. 

API-Managers often have the ability to host different versions of an API in different areas of the system that are e.g. only accessible to certain groups or networks. This is often in the form of simple sandbox and production areas however, as vendors evolve their solutions, it's now more easy to define many environments e.g. dev, test, prod and move the API's seamlessly through each of the environments.

Runtime Architecture

 I'll revert to a diagram to get us back on track and break all those functions down into manageable units. Although I've said that API Management has x,y or z capability in fact API-Management is not a single server.

The diagram above shows that there are usually, at least, three servers involved. 

API Designer

Starting at the beginning,.. designing of the API happens from within its own separate server. The configuration of the actual API's is stored in a registry (sometimes built in to the designer) ready to be pushed out to the gateway server. It is not uncommon to find that the design server is switched off when API's are not being designed as it may not serve any other purpose (but this is vendor specific).

These servers always expose a GUI to the user to allow easy creation of API's.

This designer server will often double up as the monitoring and usage tracking server later on in the life-cycle of the API.

Gateway Server

The gateway is the real 'runtime' server in this architecture. Its role is to do all that security, throttling and usage statistics monitoring that we've discussed above.

API Store

The API store does what it says. It's where the developers come in and find out what the APIs are and where they can find them. The store must be accessible to the writers of the API - but it needn't necessarily be available to them at runtime so it may be that, for security reasons perhaps, the API store is not switched on all the time. I've put it in the DMZ in the diagram above so that it can be exposed to external users but this may not be necessary depending on who's writing the application that uses the API.

Of course all these servers are linked in some way and there may well be a separate registry that contains the configuration information for the platform as a whole. depending on your vendor and configuration.

Conclusion

I hope that I've shown you that API Management encompasses a whole host of different functionality. At the moment different vendors have different capabilities in each of the areas we've discussed but they are converging into some common functions that they all support. The runtime architecture helps to distinguish the different roles and responsibilities that go with those functions.