FMW 12c: In-depth look into Oracle API Catalog (OAC)

[repost of article at AMIS Technology Blog on November 14th, 2014]

With the release of Oracle Enterprise Repository 12c another product was released. Oracle API Catalog 12c (OAC) allows you to build a catalog of your organization APIs. OAC provides a layer of visibility to those APIs so application development knows what and which one to use.  OAC includes a simple metamodel for an API asset, automation to populate OAC, and the ability for users to search OAC for APIs and understand the details of the APIs to assess their fit in the user’s application.

Installation

I’m not going to bore you with the details about the installation by giving a installation guide. It took me about 40 minutes from scratch (excluding downlOERoad time). The steps are describes in the installation guide Oracle provides. OAC is part of the OER 12c installation jar, but can be licensed and installed, as an own managed domain, without licensing and installing OER.

The steps to take on high level (from scratch):

1. Download and install Oracle Database, Fusion Middleware Infrastructure 12c, Oracle Enterprise Repository 12c, RCU patch 18791727 and Weblogic patch 18718889 (these last two are important, else you can’t install OAC).
2. Run RCU (oracle_common/bin/rcu.sh|bat) and create the OAC repository
3. Run Weblogic Domain creation (weblogic/bin/config.sh|bat) and create a new which includes OAC.
4. After installation and startup of weblogic and managed service you can find the OAC console at url: http://serverhost:8111/oac

Note: if you harvesting from another weblogic server (like SOA Suite 12c), the weblogic patch should also be installed there.

Taking the first steps

When taking my first steps the official getting started guide can help you a lot. OAC has four high-level features. OAC collects services, it has a harvester which creates API assets in OAC. After harvesting you can add metadata to the API assets like description, tags and documentation. After harvesting and editing an API asset it can be published so it is visible for application development. Published APIs can be discovered and used  through the API Catalog console and via the Oracle JDeveloper Oracle Enterprise Repository plug-in.

Logging in for the first time

After installing FMW & OAC 12c and starting the Weblogic server you can login into the provided OAC console (default) running at http://serverhost:8111/oac.

The default username and password is admin / weblogic1. The first time you are asked to change the password.

After changing the password you will login into the console. The dashboard will be empty because no APIs are harvested yet. But when APIs are harvested they are listed at this page. On this page you can also navigate to “My APIs” which list the API you bookmarked.

As admin, navigate to “Admin”, you can configure Users and Departments, control Sessions, change System settings and Import/Export the catalog. This blog will go in to the Admin features later on.

Collecting / harvesting services

The first activity is to harvest APIs into OAC. The harvester is used to populate OAC with API assets from SOA Suite and Service Bus or other deployed services. The harvesting process can be run from the command line or can be integrated into the build process. The latter can be used to automatically do the harvest at build time. Harvested API assets will get a “Draft” state and won’t be visible to developers yet.

For this blog I will use the command line harvester. There are to types of harvesters; one for SOA Suite, OER & File-based assets and one for harvesting OSB. I will use the first harvester and use it with integrated SOA Suite 12c environment.

For this blog I changed the HarvesterSettings.xml, which is decribed here, and added OAC en SOA server information, including projects to harvest.

Doing it like this you don’t have to add any parameters to harvest.sh|bat. If you want to harvest a specific asset you can use the command line properties, for example another SOA composite.

The result after running the harvest command should look something like on the image below (in preview mode).

View harvested APIs

After harvesting you first asset(s) you can login the OAC console to see the result. Assets that are harvested will get the “Draft” status, thats why  after logging into the OAC console again, no APIs are published and visible on the dashboard. Search on Service Type = Draft to view newly harvested APIs.

To see, edit and publish the API asset details click on the specific row. The details page opens which shows information about the asset like Type of Asset, Endpoint, Harvester properties and WSDL summary including namespace, porttype and methods.

Besides the details you can perform some actions (from left to right):

Link, toggle view, bookmark, edit & delete

• Link to details page: Get URL of API asset details page you currently look at and can share.
  Example: http://soabpm:8111/oac/index.jsp?assetid=50003&renderMinMaxButton=false&renderNextPrevButtons=false

Toggle between tabs and view all: You can view the API asset details in tabs (tab per category) and view them on single page like displayed above.

• Add to My APIs: Click to bookmark API. After bookmarking API it is visible under MyAPIs page.
• Edit details: Page to edit API asset details. More about this below.
• Delete items: Delete the API asset from the repository.

Add metadata to harvested API

To add metadata or edit other details of an API asset click on the edit icon/button to open the Edit Asset page. On this page you can change the name, change the version, add keywords and descriptions, but also add a link to documentation URL and assign/upload an icon. To publish an API change the API status from Draft to Published. It is also possible to set the API active status from Active to Retired.

Publish a draft API

To publish an API you just need to change the API status to published and saving the asset.



On the overview page the API status is changed and the API details can be exported to Excel and PDF.

When going back to the dashboard the recently published API is visible. When you click on the name of the API asset the user is redirected to the details page.

On both the dashboard as on the Asset detail page reviews are mentioned. The admin user can’t perform this action. For this we will create some new users.

Sharing the APIs with other users

After taking the first steps the APIs can be shared with other users. To do so new users can be added with specific roles. As admin user click on the “Admin” menu item and choose the Users section (selected by default). From this page new users can be created, you can search for users and edit & delete users.

Add, search, edit and delete users

To create a new user click in the Users section on the Add User icon on the top-right of the page section. The Create New User page is displayed. The page is divided into three sub sections; user information, roles and departments. The user information section contains form fields for the username, password, real name and email & phone information. It is also possible to force changing the password and allow the password to never expire. A user can have one of four statuses; Active, Inactive, Lockout (after 3 failed logins) and Unapproved.

The roles section gives the opportunity to give the user specific access. The admin role gives you access to harvest, edit & publish API assets and manage application settings liked described in this blog so far. The curator can harvest and edit & publish API assets and the developer can access / search published APIs.

The department section gives the opportunity to add the user to a specific department. Departments is not more then just a filter of which users belong to that department. It is not necessary to add the new user to a department.

To see user details and change user information or even delete a user go back to the Users section. To see user details click on the name of the user and you will be navigated to the User Details page. You can also search on department, role and status. The latter can i.g. be used if a user is lockout of there account. To delete a user just checked the box in front of there username and click on the Delete button.

The User Details page shows the same sub sections; overview and roles & departments the user is assigned to. The interface is very universal throughout the application. On this page you can also switch to tabbed mode, one tab per sub section, and able to navigate to the edit page, duplicating the user (create new user with same roles and departments) or deleting the user from the repository.

Also create a user, developer1.  with the Developer role.

Switching user

To switch to a different user you can sign out of the OAC console by selecting the “Sign Out” options under your user menu. Just click on the arrow on the right side of your name.

Logging in as Curator will give the same functions as an Administrator, but without the Admin tasks.

Logging in as Developer will give even less options. A developer can only search in published API and add APIs to there favorites.

Adding an API to My APIs and reviewing the API

Als user you can add APIs to you favorites (My APIs). To add a API to your favorites go to the API asset details page and add the API to My APIs by clicking the “Add this to My APIs” button. After adding it to My APIs the details page is update and shows how many times it is added (usage) in the past 6 months. Users that have added the API to there My APIs can review on the API asset.

When you click on the “View Usage History” link a pop-up is opened which shows a graph with usage over past months and which users uses the API.

To view all API that the user had added to My APIs the user van click on the “My APIs”  menu item. The My APIs page shows all the APIs the user has added and gives the user the opportunity to view the details by clicking on the name of the API, to write a review about an API or to delete an API from the list.

To write a review about an API click on the first (review) icon on the right side of the APIs name. A pop-up is opened with a form that the user can use to submit a review. The user can give a rating and a comment (max 4000 characters). After submitting the review the page is redirected to the a page which displays all reviews.

Other administrator tasks

View sessions

The administrator can perform some other tasks that I didn’t discuss yet. On the Sessions section page all (active) sessions are displayed and an administrator can look into the details of the session. An administrator can also delete sessions, which means if a user is active in the console the user will be logged out.

System settings

An administrator can change a lot of setting to change the behavior of the OAC console. The system settings page is divided into four main sections; Functional settings, Server Settings, Enterprise Authentication and Import and Export settings (not the actual import/export).

The functional settings sections contains settings for search results and printing details via PDF:



The server settings section contains settings for embedding HTML in asset details:



The Enterprise Application section contains settings for connection to a LDAP server for user management:



The Import/Export sections contains settings for setting timeouts:

Import / export repository

The import / export of the repository can be done in the corresponding section, but instead of it being done in the web UI it uses java Webstart.

My Verdict

To conclude this blog post I will give my verdict about Oracle API Catalog 12c. In the last week I had some ups but also some downs. I started on my windows laptop and installed everything locally. At first everything seemed fine, I could harvest my first Asset, but after trying to view the details I got a error after another. In the days that followed I was helped by Oracle Development and in special by Mark Dutra, but we couldn’t figure out what the problem was. I think it has something to do with security settings and how the laptop is configured (domain wise).

After creating a Linux VM and installed everything again I finally had success and the tables were turned. I really like the interface, it is very clean and uses a common workflow on every page. The use of a separate harvester (command-line or ANT task) is in one way a great solution, because you can use it in your already existing build process, but I missed the option to do this using the OAC console, you don’t always have access to use scripting.
The harvested APIs are added as Draft and an admin or curator can edit the information and publish the API. This version is a great start with lots of information already, like the endpoint, WSDL/WADL summary including methods and message payload. But I miss the possibility to register dependencies between APIs. If API are harvested from one service the separate APIs are not linked to each other.

Adding APIs to your  My APIs and the possibility to write a review can be handy. The simple metrics tell you about the usage and who uses it which is already usefull, hopefully in the future more metrics will be available in OAC.
As an administrator you can perform a lot of tasks using the UI. Adding users, looking at active sessions and import/export the repository. It worked fine on Linux, but on windows I had no result. Also the possibility to connect to an LDAP will make it much easier to add users and departments.
Pros:

• Clean and easy UI with common workflow on most pages
• Harvest through command-line (run-time) or ANT (design-time build)
• Possibility to edit Assets and add documentation
• Review on API and give feedback when an API is not working correctly
• Metrics about usage
• A great set of administration tools

Cons:

• Does not work well with Windows.
• Catalog features are still basic, no dependency viewer
• No online harvester, you can’t harvest via the OAC console