This is a quickstart introduction to the JBoss Apiman project which is arising more and more interest in the Community.
Why do we need a Management API system ? Let’s start from a simple use case: that is you have some Web services which are published through a WSDL which defines the Contract to be used by the Clients to invoke them. So far so good. However can it be better ? for example, what do you know about the Organization that publishes the Services ? do you know which policy governs the Web services (e.g. what kind of authentication or any restriction in the usage of the services) ? also as Producer of these services are you aware of your consumers or the metrics of your services ?
Most of the time you will need to develop additional layers in your applications to manage these aspects however with JBoss Apiman you can have out of the box the following features:
- Centralized governance policy configuration
- Tracking of APIs and consumers of those APIs
- Easy sharing and discovery of APIs
- Leveraging common policy configuration across different APIs
In a nutshell the Management API is a gateway to your Services which provides you all the above features above mentioned. Before getting into a very basic example we need some terminology. The Management API is based on the following three elements:
AAn Organization is the top element which acts as container for all APIs, plans and policies provided by a company. It can match a whole organization or a part of it.
BA Plan, on the other hand, defines the level of services which are provided through policies. By using plans you will be able to define multiple different levels of service for their APIs, based on policies.
CA Policy defines an Action to be performed by Apiman gateway when a request for a Service arrives. Policies are at the lowest level of the data model, and they are the basis on which the higher level elements of the data model are built.
Building your first Management API
In order to build your Hello World APIMan, we will need to perform the following actions:
- Install APIMan
- Register a Producer and Consumer user
- Define an Organization for both the Producer and the Consumer
- Define a Plan, a Policy and expose an API for the Producer
- As Consumer, register to the Producer API
Step 1 Install API Man
Installing APIMan is just a matter of Downloading a WildFly application server and patch it with a zip file which will add modules and Web applications which are the UI of APIMan. Assumed that you have already downloaded and installed WildFly 10, just download the Apiman overlay zip file: http://downloads.jboss.org/apiman/1.2.6.Final/apiman-distro-wildfly10-1.2.6.Final-overlay.zip
$ unzip apiman-distro-wildfly10-1.2.6.Final-overlay.zip -d wildfly-10.0.0.Final
Now Start APIMan:
$ cd wildfly-10.0.0.Final/bin $ ./standalone.sh -c standalone-apiman.xml
Step 2: Register a Producer and a Consumer of the Management API system
Click on New user? Register and fill in the form for two users:
Step 3 Define the Producer Organization, Plan and Policy
Now login as Producer. As first thing you will need to define your Organization. Click on Create new Organization. Next Create a Plan for your Organization. Click on the New Plan Button.
The Plan at the beginning is just an empty wrapper for your Policies so we will define a new Policy. There are several Policies out of the box available: we will choose a Rate Limiting Policy which will put a constraint on the number of requests for your Services. In our case we have set it to 10 maximum request a day for your Client Apps.
Next let’s register one API. An API is typically a SOAP/JSON based Web application but it can be also an Hello World Servlet as in our case.
Next, register your application to a Plan: please notice that you are allowed to choose if your API is a public API. Public API can be invoked directly by Clients without a Contract. We will see in a minute how to register a Contract on the Consumer for the API.
Finish by Publishing the API so that you will be able to find it by your Clients.
Define the Consumer Organization and Contract
On the Consumer side, register as well an Organization as we did for the Producer. Now click on Find/Consume an API where you can find APIs you wish to consume.
click on Create Contract. Creating a Contract allows you to connect a Client App to an API via a particular Plan offered by the API. You would want to do this so that your Client App can invoke the API successfully. Note that this is not necessary if the API is public.
When an API Contract is created, the system generates a unique API key specific to that contract. All requests made to the API by a Client App through the API Gateway must include this API key. The API key is used to create the runtime policy chain from the policies configured on the API, plan, and client app..
Now that you have created a Contract, go back to your Consumer Organization and click on APIs. You will be able to discover the URL that can be used to invoke your API proxied by the Gateway (You have to click on the (i) Link).
In our case the URL which includes the API key is: https://localhost:8443/apiman-gateway/Basicorganization/MyServlet/1.0?apikey=6143e048-2309-4262-8b53-54e69988186b
Test the application
We are ready to test our application! Invoke it through the apimain-gateway:
wget --no-check-certificate https://localhost:8443/apiman-gateway/Basicorganization/MyServlet/1.0?apikey=6143e048-2309-4262-8b53-54e69988186b
You should notice that after you exceed the numer of request allowed by the policy an Exception will be raised, preventing further invocations.
Adding a Basic Authentication Policy
So far there are no security restrictions on our Service. We will add a Basic Authentication to prevent anonymous usage of our API. Let’s create a new Version of our API, by clicking on new Version. In this new Version define a new Basic Autentication policy. The Policy will be bound to a Datasource which has been formerly defined in the WildFly application server which hosts APIman. All you have to enter is the Datasource JNDI name and the Query used to fetch check the username/password as we usually do on Login modules.
Here is the updated list of Policies for your Service:
Now republish your APIs. On the Client side you have to attach your Contract to the new Version, in our case version 2.0.
When you are done, check again your API throgh the gateway. You will see that an user/password Basic Authentication challenge will appear. Enter the username/password combination registered in the USERS table of your database to access your API.
That’s all! Hope that you enjoyed this first trip on the Management API. Check the http://www.apiman.io/latest/user-guide.html for all details about this great API!
