HOWTO: APIMAN manage API accounting: smart city API, broker API, etc.

In Snap4City, it is possible to provide accounting about the API usages. For example, for each user one could count the number of accesses to a given API and/or the volume of data provided. The business models which can be set up depend on the API manager used. We tested a number of them and we propose to use the APIMAN:

Extensible Open Source API Management

APIMAN makes managing your APIs easy. With just a few clicks you can get APIMAN running, putting a platform at your fingertips that covers the whole API Management lifecycle. Whether you want to offer existing APIs to external consumers in a secure way, or have a centralised location to discover and govern APIs, Apiman has you covered. But that's not all. Apiman is designed to be easy to customise, and you can implement your own functionality by writing simple Java plugins.

APIMAN supports multiple policies:, it can be installed on Dockers, etc.

We tested and stress tested as an API manager in front of Smart City API, Super Smart City API and Orion Broker API

APIMAN is provided with a very intuitive and easy to use User Interface (UI), it is compatible with authentication from a Keycloak authentication server (same manufacturer), the integration of an external Database such as MySQL is available
and, finally, it is possible to instantiate its image on a Docker container via docker-compose.

It is an open-source project dealing with API Management. APIMAN is aimed at four macro categories of users:

  • API Providers
  • API Consumers
  • Management Administrator API
  • API Developer

By making the following features available to these groups:

  • API Manager: this allows the API provider to use the web UI to define the different plans provided by its APIs on multiple services, possibly also allowing a "role based" control for users. These plans can manage access to it and limit its use to their own consumers. The same UI allows API consumers to easily find the APIs of interest which are always available through REST requests.
  • API Gateway: The gateway applies the policies imposed by the API Manager on every request made to the APIs. The API consumer accesses the API via a URL provided by the API Gateway as a proxy for the API. If the imposed rules allow access, then the API Gateway (via proxy) makes the request to the backend, where the implementation of the API resides.
  • A Plugin-based Architecture: Developers can create their own policies and add them to the APIMAN system.

The Data Model

A hierarchical model structured as in the following figure is used.

Figure: API Man Data Model

Organization – Occupies the top level of the hierarchy. An organization owns and manages all elements of what concerns the company, a group within the company or a circle of users. All plans, APIs and Client Apps are defined within an APIMAN organization, so that organization acts as a "container". Users, based on the role granted by the organization, can or cannot view/interact/modify a particular element (See next figure).

Figure: Role creation

Plan – Plans allow you to adjust how you access an API. For example, an organization might offer a "Gold" and a "Silver" plan for the same API. The former may be more expensive for the user, but granting privileges that the latter plan does not grant. Below are some screenshots aimed at showing the APIMAN UI and its degree of customization.

The next figure shows the new plan summary screen

API – Represents the real back-end of the APIs that are managed byAPIMAN . An API can be public (available to everyone at a static endpoint) or private (callable from a Client App created and managed by APIMAN). Entering an API into the system is very intuitive.

Client App – Represents a piece of software that needs to use one or more APIs managed by APIMAN.

To use them, however, a CONTRACT must be stipulated which brings together a Client App with a specific API by adopting a specific pre-established plan.

Policies – They are in the lowest level, but they are undoubtedly the most important concept of the project. Basically everything that is defined and managed within APIMAN is to be able to apply the right rules to the right element. There are various types of policies that can be applied to API requests.

For example, it is also possible to create a rule on the amount of data available for transfer available to users, just go to the menu for creating a new Policy and fill in the form.

Proxying requests

Whenever the API Gateway receives a request at runtime, the chain rule of the policies is applied, starting from the Client App, then applying the rules foreseen by the plan, and finally those of the API. If no intermediate errors occur (such as exceeding the daily request limit) the API Gateway sends the request to the API.

Subsequently, when the API Gateway receives the response from the back-end implementation of the API, the policy chain rule is applied again, but this time in the opposite direction. If there are no errors in between, the client receives the response.

Limitations and Policies

APIMAN, as mentioned, provides three policies to limit the use of the API:

  • Rate – Manages the number of requests to an API in a given time frame which can be set to very fine detail, such as seconds, minutes, hours, days, months or years. (example: 10 requests per second);
  • Quota – It works the same as the previous rule, but it is used for small quantities. (example: 10,000 requests per month);
  • Transfer Quota – You can set the amount of data exchanged instead of the maximum number of requests.

API Metrics

Once an API has been created and managed, it is possible to monitor its use, taking into account:

  • Start and end time of requests;
  • Time required to process the request (back-end side);
  • Answers given (success, failure, error);
  • Download/upload byte This information can be accessed via the Management UI available by navigating within APIMAN.