...intro to apiman

I’ll be introducing apiman in a series of blogs, and I’ll try to provide insight into the usually not very well documented parts, like deploying, scaling and providing HA. But for this purpose, I need to provide some details about apiman, the concepts, and the basic architecture.

Description of API Management

I will not write what is already written, so a good description is here provided:

API management is the process of publishing, promoting and overseeing application programming interfaces (APIs) in a secure, scalable environment. It also includes the creation of end user support resources that define and document the API.

The goal of API management is to allow an organization that publishes an API to monitor the interface’s lifecycle and make sure the needs of developers and applications using the API are being met.

API management software tools typically provide the following functions:

1-Automate and control connections between an API and the applications that use it.

2-Ensure consistency between multiple API implementations and versions.

3-Monitor traffic from individual apps.

4-Provide memory management and caching mechanisms to improve application performance.

5-Protect the API from misuse by wrapping it in security procedures and policies.

— http://searchcloudapplications.techtarget.com/definition/API-management

Concepts

Although, there is a very nice and short video that can be easily seen introducing the apiman concepts, I will provide here with a human readable description of the core concepts.

• Organization: Anyone that wants to expose their APIs. The owner of the APIs.
• Service: Usually, the APIs to be exposed. A service represents an external API that is being governed by the API management system.
• Application: An application represents a consumer of an API. Typical API consumers are things like mobile applications and B2B applications.
• Plan: conditions/contraints that govern all the services for an organization, a concrete service or an application. These can be rate-limiting, security, white/black listing, caching,…​ A plan is a set of policies that define a level of service.
• Service contract: A service contract is simply a link between an application and a service through a plan offered by that service. This is the only way that an application can consume a service.

There is much more to it, that can be read in the docs. Although a work in progress, the concepts are already written.

Use cases

API Management can be used in different scenarios.

Within an organization (On premise)

An Organization wants to have control of their APIs, and can use an API management solution to expose and control these APIs consumption, whether internally or externally. In these cases, the internal department in of the APIs will be the Organization, in apiman terms.

In the cloud

An Organization wants to expose their APIs, and they rely on a public cloud API Management solution that will provide with all the requirements to control/govern/monitor/monetize the APIs being exposed. In these cases, the apiman Organization will map to this Organization.

Basic architecture

apiman is composed of 4 architectural pieces:

• APIManager UI: User interface layer for API Management. It is only a frontend, and makes REST calls to the APIManager backend which is the one having the information.
• APIManager backend: It exposes a set of REST interfaces for managing the APIs. It is the one holding the API Management information (data model). Every time an API has to be published, it communicates via REST with the APIGAteway Config.
• APIGateway Config: It is the layer for managing an APIGateway. It exposes a REST interface for management, and stores the management/configuration state.
• APIGateway Runtime: The APIGateway Runtime will be primary runtime component of apiman, and will proxy requests from consumers to the services, applying a set of policies for delivering the service. This is the endpoint that will be known by applications. This will be the single source of requests to the services (APIs).

There will be different implementations for the APIGateway, in order to fit different architectures and technologies. Currently available are:

• Undertow
• Vertx
• Servlet
• Wildfly8 War

Consuming services

Whenever apiman exposes a private service, it will hide the real endpoint, and uses a apikey for the application to identify the service contract. The enpoint used in a private service will be:

http://gatewayhost:port/apiman-gateway/{organizationid}/{serviceid}/{version}/

Anything after that will get passed through to the service impl.

So if you created a service named MyOrg / MyService version 1.0, and set the service implementation endpoint to http://myhost:8080/myservice Then your client would make managed calls to this endponit:

http://gatewayhost:port/apiman-gateway/MyOrg/MyService/1.0/path/to/resource?query=12345

And the gateway would proxy that request to the back service at this endpoint:

http://myhost:8080/myservice/path/to/resource?query=12345

Requests to managed endpoints must include the API Key so that the Gateway knows which Contract is being used to invoke the Service. The API Key can be sent in one of the following ways:

• As an HTTP Header named X-API-Key
• As a URL query parameter named apikey

All HTTP headers and all query parameters (except for the API Key) will also be proxied to the back-end service.