API Management on Fabric8

Summary

The Fabric8 project comes with an HTTP-Gateway to create a single entry point to all Micro Services hosted by a particular Fabric8 deployment, making it easier to route all service traffic through an external firewall. It also allows you do create URL mappings using a template. On top of the regular gateway features the Fabric8 HTTP-Gateway offers API Management features. This article is an introduction into how to use these. Both the HTTP-Gateway as well as the API Management capabilities are fully asynchronous.

It is assumed that you are already familiar with fabric8 version 2. If you are not please take a look at the fabric8 docs first.

 

 API Management

The Fabric8 HTTP Gateway leverages the apiman.io project, which 'brings an open source development methodology to API Management, coupling a rich API design & configuration layer with a blazingly fast runtime'. A popular trend in enterprise software development these days is to design applications to be very decoupled and use API’s to connect them. This approach provides an excellent way to reuse functionality across various applications and business units. Another great benefit of API usage in enterprises is the ability to create those API’s using a variety of disparate technologies. However, this approach also introduces its own pitfalls and disadvantages. Some of those disadvantages include things like:

• Difficulty discovering or sharing existing API’s
• Difficulty sharing common functionality across API implementations
• Tracking of API usage/consumption

API Management is a technology that addresses these and other issues by providing an API Manager to track APIs and configure governance policies, as well as an API Gateway that sits between the API and the client. This API Gateway is responsible for applying the policies configured during management. Therefore an API management system tends to provide the following features:

• Centralized governance policy configuration
• Tracking of API’s and consumers of those API’s
• Easy sharing and discovery of API’s
• Leveraging common policy configuration across different API’s

 For more information on apiman see also their user guide.

 

Common Use Cases

Some common use cases most developers encounter are:

Throttling/Quotas - Limit the number of requests consumers of your APIs can make within a given time period (per service contract or per end-user).

Centralized Security - Add authentication and IP filtering capabilities in a central location, freeing your back-end services to focus on functionality.

Billing and Metrics - Easily get metrics for all your APIs so you can see what's popular or charge your consumers for their usage.

APIMan in Fabric8

The Fabric8 HTTP-Gateway contains this runtime 'embedded API manager engine'. As can be seen in Figure 1, the HTTP-Gateway opens a port at 9000 on xUbe. xUbe refers to either Kube (Kubernetes, OpenShift 3 and Docker) or Jube. By default the HTTP-Gateway has API Management turned on. This means that you will have to configure services in apiman and then 'Publish' them before they are live on the Gateway. When a service is published, an external request to this service on the gateway is routed through the apiman engine where policies are applied before the xUbe Service is called. An example of such a service is the CxfCdi Quickstart example which runs as Java Main processes. xUbe relays the request to one or more pods. When running Kube, the pod will typically open the same port number on the container as the service is running under. For Jube everything runs on the same machine so this would result in a port conflict and in this case an open port is chosen by Jube. In Figure 1, the port number is marked as 'xxxxx' as this port is not predetermined in this case.

Figure 1. Fabric8 API Management 

APIMan Console

The apiman console is shipped with fabric8 as a default application that can be run. The apiman application is deployed onto a wildly-8.1 container. From the console a service can be published to the Fabric8 HTTP-Gateway using REST management that run on port 8999 on the gateway. The console itself runs on http://:9092/apiman-manager/. The console is a self-service console where service creators and consumers can set up service contracts between them determining the terms of usage for a certain service.

 

Setup a rate limiting policy on the CxfCdi service in 5 minutes

From the Hawtio console (Kube: http://localhost:8484, Jube: http://localhost:8585) and under "Runtime > Apps" click on the green "Run..." button. Note that in this example I am using Jube, which means that my is "localhost". This brings up a screen from which you should select 2 applications "HTTP Gateway" and "ApiMan Console", and one Quickstart/Java "Quickstart : CXF JAX-RS CDI". Then click the green "Run App" button. After a little while, on the "Runtime > Apps" tab you should now see three green "1" icons in the 'Pods' column of each of these applications, as shown in Figure 2.

Figure 2. Hawtio Console, with running Gateway.

Now open the apiman console by navigating to: http://127.0.0.1:9092/apiman-manager/, and you can login using admin/admin123! You should change the password in the keycloak console at http://127.0.0.1:9092/auth/.

Figure 3. Login into the apiman console.

We will be using the admin user, but on this screen new users would register themselves. Once logged in you should see the apiman home screen as shown in Figure 4 below.

Figure 4. The apiman console home screen.

The first you need to do is to navigate to "Manage Gateways" and to remove to existing "The Gateway" gateway and to create a new "Fabric8Gateway". The Fabric8Gateway should have an endpoint of "http://:8999/rest/apimanager". Add any credentials as they are (not yet) used.

Figure 5. Create a new Fabric8Gateway.

Next you need to add an Organization called "Fabric8Org", and now we are ready to create the CxfCdi service under this organization. We are going to create a "Public" service so we don't need to create a contract or any additional users - let's get the simple case working first! So click on "Create a new Service" from the Home screen. On the New Service screen select organization "Fabric8Org", set the name "CxfCdi", version "1.0" and description "Cxf Cdi Quickstart Demo", then click the "Create Service" button.

Figure 6. Service Implementation.

Make sure you can reach the CxfCdi service endpoint by doing GET on http://:9002/quickstart-java-cxf-cdi/cxfcdi/customerservice/customers/123. This should return a small XML structure 123John. Now, as shown in Figure 6, add http://:9002/quickstart-java-cxf-cdi in the API Endpoint box and select type "REST". Click Save and under plans select "Make this service public". Then under Policies select "Add Policy" and select a "Rate Limiting Policy", with 5 requests per service per minute.

Figure 7. Add Rate Limiting Policy.

You are now ready to publish the service to the Fabric8Gateway, so go to the "Overview" tab and click "Publish". Figure 8 shows the that the status will go to "Published".

Figure 8. Publish Service to the Fabric8Gateway.

The service is now exposed on the gateway and it should show up in the mapping page at http://:9000 which should respond with a JSON structure showing the mapping

{"/quickstart-java-cxf-cdi":["http://localhost:9002/quickstart-java-cxf-cdi"]}

and now we should be able to approach the service through the gateway at "http://:9000/quickstart-java-cxf-cdi", so go ahead and do a GET on "http://127.0.0.1:9000/quickstart-java-cxf-cdi/cxfcdi/customerservice/customers/123" which should respond with the same small XML structure 123John. However the 6th time in a minute it will respond with a 403 instead stating that the Rate limit was exceeded.

Figure 9. Rate policy triggered.

After a minute the service should become responsive again. You are now ready to set up more complex contracts in apiman.

Cheers!

--Kurt