Oracle has introduced a new product; API Manager (you can find the official documentation here). API Manager is an important addition to the already impressive Oracle SOA stack. In this article I’ll explain what this new product does and how it helps in managing your API’s. I will focus on the features and benefits you can have of this product and also elaborate a little about my current experiences with it.

API Manager

What does API Manager do?

API Manager is a product which extends the Service Bus functionality and provides an API Manager Portal to manage API’s and browse analytics. API Manager allows you to save certain metadata as part of a Service Bus proxy service. This metadata is used to allow access to an API and provide data on their usage. SOAP and REST API’s are supported (HTTP API’s).

As you can see in the screenshot, you can set an API as managed or unmanaged. If an API is managed, you can only call it if you have a registered subscription. A subscription allows you to use an API key (HTTP header X-API-KEY) in order to access the API. Requests to managed API’s which have not specified a correct key, are denied.

If you test an API from inside the Service Bus console or Fusion Middleware Control however, you can still call the service without an API key.

API Manager workflow

API Manager uses several (application) roles.

Developer / Deployer

This role is not specific to API Manager. The API Developer creates a new API. Someone with the group membership Deployer can deploy it to the Service Bus.

API Consumer

The API Consumer can access the API Manager Portal, browse API’s and register as subscriber (generate an API key and use it in requests).

API Curator

The API curator is able to set service metadata in the Service Bus console. An API Curator can publish a service so it becomes visible in the API Manager Portal or set it deprecated.

API Administrator

The API Administrator can view analytics and can import/export metadata using WLST scripts.

API Manager Portal

A subscription can be created for an API consumer in the new API Manager Portal. This is accessible at http://[host]:[port]/apimanager/. The API Manager Portal is a clean easy to use interface. It uses several application roles which need to be configured before you can access the portal. API Curator, API Administrator and API Consumer. This is described in the installation manual.

Inside the portal, you can access 3 tabs; Subscriptions, Analytics and Catalog. Inside the Catalog and Subscriptions pages, you can create subscriptions. You first have to create an application in order to add subscriptions to it. An application has an API key and all API’s part of the application use the same key.

You can not subscribe to an API which is not published (it is not visible in the portal and if it is visible because you just updated the state, this is denied). Also you can not create new subscriptions for a deprecated API. The API state (published, draft, private) and if it is deprecated, can be set in the Service Bus console.

The configuration done in the API Manager Portal can be imported and exported as a configuration JAR using WLST.

Using API Manager

Publish the service

One of the features API manager provides is Service Bus proxy states. When you publish a service, it is not available externally but gets the state ‘Draft’. When you call this service you get an HTTP 403 Forbidden. You have to specifically tell it to publish the service.

Can’t update the API key?

I did not see a mechanism in the API Manager Portal to update an API key. Probably this can be done ‘the hard way’ by looking at the database. Maybe you should ask yourself why you would want to change this key.

Key propagation

When using composite services as API, you will need to propagate the API key in service calls. The Service Bus and BPEL have their own mechanisms for this. Other components will also have their own way of doing this.

Circumventing API Manager

I was curious if I could circumvent the API Manager API key header check. When I have two Service Bus proxy services. One of the services is managed and other is not. The unmanaged service calls the managed service without API key. The call from the unmanaged service also gets an HTTP 403 message. This is a very good thing! It allows API Manager to manage internal and external API’s. If a service wants to use another service, it has to be registered as subscriber (if it is managed). I have not tried using a Java API or direct binding to call the service.

Some other things to mind

Upgrade existing DB schema’s

The API Manager Installation patches the Repository Creation Utility. If you create schema’s with the patched RCU, you can use API Manager. I have not seen (could have missed this) a mechanism to upgrade existing database schema’s with the functionality required by API Manager.

Service Bus extension

API Manager can be used for Service Bus Proxy services. I have not yet seen support for other Oracle SOA components/composites. This is understandable since it is a good practice to use the Service Bus in front of other components. It would be nice though if it is not dependent on a Service Bus implementation.

Installation

I followed the standard installation and created 3 users which were in the groups API Administrator, API Curator and API Consumer. I had assigned the application roles as described. I could have made a mistake though. When I tried to access the API Management Portal, I could only log in with the API Administrator role. The other users were not allowed access. None of the users were allowed access to the Service Bus Console (after login I got HTTP 403 Forbidden messages). The API Administrator user did not have enough permissions (I could for example not create or view applications). In order to write this article, I have created a superuser which was assigned all groups. With this user I could access all the required functionality to get everything working. My idea is that more permissions are required to use the described roles. I have not looked into this further.

No analytics?

During the writing of this blog I did not see any analytics data. Later I found out this was caused because I did not indicate the service should be monitored in the Service Bus console API tab. Do not forget to enable it if you want to use this feature!

Conclusion

API Manager adds important new features to the Oracle Service Bus. It provides a mechanism to secure API’s, provide insight in consumers and allows more active management of the API lifecycle. This product does not work on a harvest of services to allow adding of metadata but it works on the actual service as you can see it in the Service Bus console. This allows true management and does not provide an abstraction which might become out of sync with the actual situation.

In order to use it though, some (minor) code changes are required. You need to supply a specific API Manager HTTP header when you want to access a managed service. This API key can be different per environment and consumers should be able to deal with these differences. Also if you want to use this, you need to look into the roles/groups/users. Using the roles though, you can implement a structured workflow which will also benefit your development process.

Because API Manager is not easily circumvented, consumers need to register in order to use an API. A danger here is that everyone starts using the same API key or every environments uses the same API key. This is of course not secure and voids the benefits of additional insight into your consumers. This insight is in my opinion the most important feature of this product. Not only do you know who uses your API (dependencies!), but you can even gather statistics on them. If for example requests originating from a certain consumer take a long time to process, you can take action and contact this consumer to maybe optimize their API usage. Also the mechanism of draft and deprecated API’s is very useful to indicate something shouldn’t be used yet or shouldn’t be used by new consumers. A developer can still test the service using the test console. In summary, this looks like a very useful product. I like it!