View the Apiman docs for specific information

It’s no surprise that the growth of the API economy has been accompanied by a proliferation of API management solutions as software vendors endeavor to tap into the needs of a wave of new API providers hitting the market. API management means different things to different people (as we recently discussed), and there are a myriad of commercial solutions available in the market with a host of different capabilities covering basic API management to full API lifecycle capabilities.

However, there are also some notable open source solutions that have made inroads in the market, such as WSO2, Kong and Tyk.io. In this article we take a look at one such open source offering, Apiman from RedHat, to see what this platform has to offer and how the solution might provide these kind of features to new and existing API providers.

Firstly, open source API management solutions are appealing to new or existing API providers for a number of reasons:

• The initial cost of an open source solution is likely to be lower than a commercial solution with the outlay focusing on infrastructure and labor to learn, installation and configuring the product rather than licensing and professional services. This may be very important to API providers who are looking to reduce initial costs when building a minimum viable product;
• There may also be benefits at the other end of the scale, with the biggest API providers with a significant API management footprint able to make cost savings on licensing across an infrastructure deployed with “money pits” like high availability and redundancy;
• Open source solutions tend to be “on-premise” (with on-premise meaning deployed in either a physical or virtual data center), which allows API providers to use a solution requiring less overall integration effort than cloud-based “as-a-service” API management solutions (as these often require special “trusted” links between the service and the API providers platform);
• API providers tend to be free to “tinker” more with an open source solution, customizing it to their specific needs by developing new components or plugins. This can be very useful to API providers with esoteric internal architectures, transports or protocols who need a solution that is not supported with a commercial product and see a customized API management solution as the best course to meeting their needs in a cost effective manner.

For some API providers, open source API management solutions can therefore offer a number of advantages over on-premise or “as-a-service”commercial solutions.

Note that this post will be a discussion on features rather than a detailed walkthrough. If you want to get hands-on with Apiman the documentation they supply is an excellent starting point and it is worth taking the time to read the user guide.

Introduction

Apiman is the JBoss open source API management solution and has been available for a couple of years; it’s currently under active development and is hosted on GitHub.

The software is built around two main components:

• API Manager: The API manager is the component where the majority of API creation and administration activity takes place. Users can define APIs and implement Policies, which are the fundamental building blocks that define their behavior (discussed in more detail below). Users can also browse the APIs that already exist and understand the Policies they implement as well as their capabilities. In terms of the taxonomy discussed in our core principles post the API Manager largely fulfils the role of the API Registry, with some additional design capabilities;

• API Gateway: This is the runtime where API implementations are deployed and exposed to consumers — very similar to our definition of an API Gateway. Apiman supports the use of multiple API Gateways, allowing the separation of APIs based on their characteristics or needs; for example, an API provider might deploy all their public APIs onto one gateway instance and their private APIs onto another, for reasons of traffic management or security. Adding additional gateways to the configuration is a system administration task that can be undertaken using the API Manager.

Getting Started

Apiman provides a number of ways to get an instance running, including the ability to embed the policy engine inside another application or run within a Java application runtime. However, the simplest method is to start a Docker container:

docker run -p 8080:8080 -p 8443:8443 -d --name apiman apiman/on-wildfly10

With the Docker container running you can log into the API Manager and start creating the configuration that will be deployed to the API Gateway. What you actually create in your configuration is largely determined by the Apiman data model.

Data Model

As with most API management solutions Apiman implements an internal model that helps API providers describe their API so they can apply management and governance to them. The Apiman model is reasonably rich, allowing elements of reuse and organizational control as described below.

Organizations

An organization describes the API provider itself and is the container for Plans and APIs, providing the management context for these entities. The organization construct allows different departments or even multiple API providers to coexist in the same Apiman instance.

Plans

Plans are the governance entity that are created for an organization and used to describe a group of behaviors that can be applied to APIs: Plans are therefore effectively reusable objects that can be applied across an organization. For example, if an API provider chose to implement a common plan across all their APIs they can do so with this object. Plans therefore include the ability to define Policies such as quotas, authorization, caching, whitelist, and so on.

APIs

The role of an API in the model is obvious, but it’s worth noting that they provide the link between the Organization and the Client App, governed by Plans. There are several different aspects to the functionality APIs encapsulate:

• Implementation: Allows an API definition to be connected to a REST or SOAP-based backend;
• Definition: Optionally allows an OpenAPI Specification document to be stored with the API;
• Plans: As described above, an API can reference one or more Plans defined by the Organization. This will enforce the Policies encapsulated by the Plan (more on this below);
• Policies: APIs can also directly implement Policies; this would be done where the behavior required for a given API is specific.

Client Apps

As they sound, client apps are a logical representation of the applications API consumers developed to consume APIs and are used to create the contractual binding between an API consumer and the API provider.

Contracts

Contracts is the actual link between an API and the API consumers, which is manifested by way of an API key. Without a contract a client app cannot consume an API unless the API is deemed public and thus does not require an API key for access.

Policies

The entities described above provide the core of the APIs you can create and publish in Apiman. As already discussed however, Plans encapsulate API Policies, which are the key construct for specifying the required behaviors of an API.

Policies are a common concept in API management solutions and Apiman uses them to enforce API consumer behavior by mandating security or entitlement. They can be applied to either individual APIs or to Plans, giving the API provider flexibility on creating common policies across their organization.

Examples of the policies included out-of-the-box:

• Authorization Policy: Restricts access to resources on APIs to specific roles;
• Basic Authentication Policy: Enforces basic authentication against an external identity provider, integrated with the Apiman via JDBC or LDAP (a local provider can be created for development purposes);
• Quota Policy: Enforces a limit on the number of calls that can be made to an API for a given period (over a day, month, or year);
• Rate Limiting Policy: As a complement to the Quote Policy, enforces thresholds on the rate of consumption for API consumers or their users, down to the level of number of requests per second.

On first impressions the range of policies are focused mainly on authentication, authorization, and access control (with access control including entitlements such as quotas and rate limits). However, API providers can also create their own using plugins and some additional policies such as XML to JSON conversion are available from the Apiman plugin registry. Apiman provides detailed guidance on the creation of plugins in Java, which can also be contributed to the Apiman plugin repository. API providers can optionally contribute to the public repository.

On first impressions the sweet spot for Apiman is likely for API providers who use Java and are happy to invest time in customizing the platform to their requirements by developing their own plugins. As mentioned above, API providers may see the need to directly customize Apiman using plug-ins for a variety of reasons, and developers will appreciate the ability to perform this customization using a language they understand with a great deal of control at their fingertips. That said, the policies provided out-of-the-box do provide a good deal of functionality and many API providers will not need to customize the platform at all.

Versioning and Control

With the exception of Organizations virtually everything in Apiman is versioned and controlled, with many of the objects supporting the ability to run multiple versions simultaneously. APIs, Plans and Client Apps can not only be versioned but also locked, rendering them immutable and requiring a new version to be created in order to deliver changes to a given entity. Indeed, Plans must be locked in order to make them available to be included in APIs.

This implementation is good from a governance perspective as versioning should be implicit in everything an API provider does when creating new APIs or Plans. However, API providers should ensure they work out their best practices for versioning in advance of using Apiman in anger: The ability to version everything could lead to many unneeded or unused versions of APIs or Plans that actually may make API management more difficult.

Conclusions

In general Apiman appears to be a very capable API management solution with good support for the kind of functionality one would expect to find in any feature-rich implementation. The core functionality is easy to get to grips with and an API can be created in a matter of minutes. The software is also extensible with plugin support, so it can be tailored to an API provider’s needs with relative ease.

API providers looking for full API lifecycle management functionality including API design, billing integration and support for a suite of API description specifications will probably need to look elsewhere at the time of writing. Interestingly billing and additional API description support are both in the roadmap for Apiman as are other useful features such as import of Swagger or WADL to create an API, the ability to fire events based on Policy execution and Developer Portal type tools such as forums and API ratings.

However, the focus on core API management functionality does not belie the fact that Apiman provides the ability for an API provider to create a reasonable complex suite of plans and APIs. Together with the ability to deploy to multiple API gateways and allow API providers to create a more complex topology, Apiman can provide a significant amount of API management functionality and could provider a very appealing alternative to commercial API management solutions.