#1024 Introduction to OIC API Catalog & Portal

 

Introduction

Many OIC customers expose the apis of their integrations to internal, and, maybe also, external developers. Usually these integrations are REST or SOAP driven, i.e. have REST or SOAP adapter based triggers. 

The management of such apis is crucial and drives the need for -

• The ability to manage the lifecycle of Integration APIs
• The ability to decide which integration apis to expose to developers
• Control over who has access to those apis

Such requirements also require a consumer/developer portal where developers can -

• Browse/Search for apis
• Try out/test apis
• Provide feedback on apis
• Get access to apis, so they can leverage them in their apps 

The Oracle Integration Cloud | API Catalog & Portal fully addresses the requirements listed above and actually does more!

So what is it?

It's a new version of digitalML's leading api management platform, ignite, which is now available exclusively for OIC. This provides api lifecycle management via the API Catalog component and developer access to apis via ignite's  Consumer Portal. This flavour of digitalML's ignite,  is available from the Oracle Cloud Marketplace.

Here is the direct link to the offering -

 

As already mentioned, this service is purely for the harvesting and management of OIC Project based integration APIs. The API Catalog allows one to define a connection to an OIC instance. Authentication is via OAuth, so one will need to define a confidential app/integration application in one's OCI Identity domain. This will generate the client id and secret, used as part of the connection definition for OIC.

From the API Catalog one can import OIC Projects and their integrations. OIC Projects can be public or private, this is achieved by applying RBAC to a project. 

Setting Can view to Everyone makes this a public project in the context of our new service. This means that I will be able to import the integrations contained in this project to the API Catalog. Private project metadata, e.g. the project name, description will be viewable in the API Catalog, but none of its integrations can be imported. 

So we have looked at how the service connects to OIC; we also looked at how Projects RBAC controls which integrations can be imported,. So with those basics addressed, let's try it out!

API Catalog 

The API Catalog is the tool for managing the lifecycle of your OIC integration apis. Within the catalog, one can also enrich the api definitions, for example, by adding supplementary documentation. The catalog admin can also decide which apis to expose to developers via the API Consumer Portal.

The following 3 options are available, when one logs into the catalog - 

• Discover - browse existing OIC projects, i.e. those that have been previously imported. Check out the integration metadata.
• Import - Import a Project and all its integrations, or selectively import specific integrations from a project.
• Reporting - Get an aggregate view of the catalog contents 

 

I click Import -

There is only one option here, as you can see. Well it is the Oracle Integration Cloud | API Catalog & Portal - 

However, there is a standard version of ignite available, also on the Oracle Cloud Marketplace, which is a generic api management platform. More details on that are available here

 

Now back to our import, on clicking OIC Import, I am presented with a list of the projects in my OIC instance - 

Some are highlighted in green, indicating they have already been imported. However, this could also indicate a partial import i.e. just some integrations have been imported.

As alluded to above, one can import a project with all of its integrations, or browse a project and import specific integrations. So let's go through a couple of scenarios -

I click on a private project, AA-ERP-Project, to begin with -

As you can see, visibility is restricted, I do not see any of the project integrations. Now to importing a complete project -

Finally, importing an individual integration - here I can open the project and browse its integrations, selecting those I require to be imported.  

Now that the import, in all its facets, has been addressed, let's look at the API Catalog view of one of my OIC projects, AA-Demo-OrderProcessing - 

Note the 4 Tabs, cataloguing the 4 types of integrations we can have in OIC - REST driven, SOAP driven, Event Driven (e.g. integrations firing on Fusion ERP business events) and scheduled.

Only REST and SOAP driven integrations are interesting from a developer perspective, however, the goal here is to give the catalog admin a comprehensive overview of the OIC projects and their integrations.

Project documentation, entered in OIC, is also surfaced here, along with keywords etc.   

Let's look at the approveOrder integration in detail - 

This screen gives us 2 views, the OIC and ignite Catalog view. Forgive me, but I have to split the screenshot because of space limits -

I now click on the ignite view link - 

This is the catalog view of the integration. I will not go through all of the sidebar menu options in depth, after all this is an introductory post, and I need to leave some content for future posts. But let's look at some of them - 

Interactive Documentation - 

Deploy to Portal - Ability to deploy this integration api to the Consumer Portal.

Methods - 

the method toolbar supports the following - 

• try it (i.e. mock server tester)
• View Payloads
• View Parameters

Feedback - supports communication with the consumer portal users. Developers can raise questions about the apis in the Consumer Portal; they can also make requests to get access to an api. In the other direction, the API Admin can raise notifications about apis that can be surfaced in the Consumer Portal. These notifications can also be sent via email to developers, once they register for such.

 

Attachments - the openapi spec for the api is the default attachment one sees.However, one can add other attachments, for example a document describing the integration/api in more detail. This new attachment could be marked so that it is surfaced in the Consumer Portal.

Export - downloads the openapi spec.

Policies - detail the security policy attached to the api, e.g. OAuth 

This api has already been published so let's check out the developer experience.

Consumer Portal

Here's my approveOrder api - 

Let's go through the menu here - 

About - provides the high level details and is the default form shown -

Methods - lists the methods/verbs supported by the api, in my case, it's just POST -

Attachments - as you can see, the api admin has uploaded an attachment to this api. The developer can, naturally, download attachments from here.

 

Documentation - here the developer sees the api details and can try it out.

Download OpenAPI Document - does just that.

Contact Provider - here the developer can ask the api admin questions. She can also provide feedback on the api.

Provider Updates - this is where updates from the API Catalog admin surface.

Get API Access - here the developer can request access from the API Catalog admin.

Now that is a very high level overview of the API Catalog and Consumer Portal. Finally, let's look at the configuration features of this offering.

App Configuration

I click on the Settings icon in the API Catalog. 

Catalog Branding allows me to have my own look and feel, logo etc.

Jobs Queue - imports to ignite are asynchronous. The jobs queue gives me insight into progress and import status etc.

Portal Management - 

The admin can create "global" portal announcements. These surface in the Consumer Portal under Latest News - Announcements.

API Access Form Configuration - here you can configure the form presented to the user when they click Get API Access in the Consumer Portal.

Portal Branding - use your own logo, configure the welcome message etc.

Email Notifications - we're back in the main menu now. 

Here you can specify when emails are sent, e.g. admin creates a new notification for an api, and the developer receives an email with the details. You can also add a regular expression for email validation, if required.

The admin can create email groups - 

You can also configure ignite to use your email server -

Finally, let's look at the synchronization between OIC and ignite - 

I can refresh the project manually, but there is also autosync available - 

So you can decide when and how you synchronize with OIC.

Summa Summarum

This is a very compelling offering for OIC customers. It fills the API Management gap we've had and provides you with a tailored solution for managing your OIC integration apis. It is competitively priced and you can pay using Universal Credits. Try it out, here again is the direct link, and please send me your feedback!