Governance made easy - Oracle API Catalog 12c

Governance made easy - Oracle API Catalog 12c

Oracle recently launched a new product in their governance portfolio. As more and more applications, particularly in the mobile domain, rely on external APIs, the need for proper governance is ever growing.

Many organizations use ad hoc tools like spread sheets and wikis to keep track of their APIs. The API Catalog 12c may allow organizations to replace these tools with an online catalog that provides visibility to their APIs for application development.

The API Catalog is a lightweight product that positions itself as a stepping-stone on the way to “real” SOA governance. It includes a meta-model for API assets and tools for automatically populating it with APIs from specified servers. Developers can use the catalog to search for APIs they want to use.

Simplified, the API Catalog seem to provide answers to three important questions:

  • What APIs exist?
  • What do these APIs do?
  • How can they be consumed?

I will describe, from a high level perspective, how the API Catalog addresses these questions and why this may be a great tool for your organization. For a more in-depth guide on using it, take a look at the blog post by Robert Van Mölken.

Figure 1: The new API Catalog 12c


There are four main steps involved in creating API Catalog assets. They are:

  • Harvesting services
  • Adding metadata to API assets
  • Publishing API assets
  • Discovering API assets

Harvest services

Populating the API Catalog with actual API´s is done with a tool called the Harvester. The Harvester is a command line tool that can be run manually or integrated into the build process. It comes in a zip file that is automatically extracted as part of the API Catalog installation process.

There are two separate harvesters, one for SOA Suite or file based (WSDLs) services, and one for OSB services.

Services can be harvested from both local and remote servers, Oracle or non-Oracle, as well as from your local (or mapped) file system.

The harvester can be run on any client that has a valid JAVA_HOME environment, by moving and extracting the zip file manually. This allows for great flexibility in how you build your harvesting strategy.

Add metadata to API assets

Adding metadata to the harvested services, greatly increases the discoverability and search accuracy. This is done using a simple editor that allows you to give the service a new display name and adding description, keywords and documentation references.

Publishing API assets

The harvester publishes services as drafts, which means they are not discoverable in the API Catalog until they have been reviewed by an administrator. This is a useful feature that prevents accidental cluttering of the catalog by unwanted services. The actual publishing is achieved by changing the status in a drop-down box.

Discovering API assets

Services can be discovered by logging into the web console and using the search functionality provided, or by using a JDeveloper plugin. Upon finding a service, you can review the details and add it to your “My API´s” page. This way, you can build a personalized catalog of the services that you use.

Install it and give it a try

If you are familiar with Oracles SOA stack, installation should be straightforward. The API Catalog comes bundled with it´s older sibling, Oracle Enterprise Repository, in a single jar-file.

It runs on Weblogic and requires an Oracle database, so you´ll need that in place before you start. This is not a howto, so I won´t detail all the steps, head over to if you want to have a go at it. Don´t skip the steps in the installation guide on patching RCU and Weblogic, or else you won´t be able to select API Catalog in the RCU and domain configuration wizards.

In short, you install the API Catalog, connect it to a database using the Repository Creation Utility (RCU), create a Weblogic domain, and deploy the catalog.

First impressions

One of the challenges of SOA Governance is bridging the gap between governance and development. If governance processes are too cumbersome to implement, your organization will not commit to them, and the processes will be undermined. Similarly, if the tools provided feel counter productive, they will not be used, or worse, they will only be used some of the time, resulting in fragmented and outdated information.

The API Catalog addresses only a subset of governance challenges, but it is an important subset. It is easy to install and get started with, and it helps you be more productive, especially if wikis and spreadsheets are your service catalogs today.

The automation capabilities will help ensure that the catalog is up-to-date, as you can integrate service harvesting in the build process.

As you use it, you will ask questions like “who else is using this API?” and “is it safe to delete it?” and you will probably want to add enforcement policies. The API Catalog doesn´t provide this kind of functionality, but that is when you´ll want to use tools like Enterprise Repository, or the upcoming API Manager, which looks like it may to be the logical next step.

The API Catalog on its own may not be where you want to be down the governance line, but it is where you´ll want to begin in order to get there.

It may just be the tool that will get your organization interested in governance, and if nothing else, that is a good start. 

comments powered by Disqus