Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 190f

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs

At the Oracle Partner PaaS Summer Camps VII 2017 in Lisbon last year, at the end of august, I attended the API Platform Cloud Service & Integration Cloud Service bootcamp.

In a series of article’s I will give a high level overview of what you can do with Oracle API Platform Cloud Service.

At the Summer Camp a pre-built Oracle VM VirtualBox APIPCS appliance (APIPCS_17_3_3.ova) was provided to us, to be used in VirtualBox. Everything needed to run a complete demo of API Platform Cloud Service is contained within Docker containers that are staged in that appliance. The version of Oracle API Platform CS, used within the appliance, is Release 17.3.3 — August 2017.

See https://docs.oracle.com/en/cloud/paas/api-platform-cloud/whats-new/index.html to learn about the new and changed features of Oracle API Platform CS in the latest release.

In this article in the series about Oracle API Platform CS, the focus will be on the Developer Portal, discovering APIs via the API Catalog and subscribing applications to APIs. As a follow-up from my previous article, at the end the focus is on validating the “Key Validation” policy of the “HumanResourceService”API.
[https://technology.amis.nl/2018/04/14/oracle-api-platform-cloud-service-using-the-management-portal-and-creating-an-api-including-some-policies/]

Be aware that the screenshot’s in this article and the examples provided, are based on a demo environment of Oracle API Platform CS and were created by using the Oracle VM VirtualBox APIPCS appliance mentioned above.

This article only covers part of the functionality of Oracle API Platform CS. For more detail I refer you to the documentation: https://cloud.oracle.com/en_US/api-platform.

Short overview of Oracle API Platform Cloud Service

Oracle API Platform Cloud Service enables companies to thrive in the digital economy by comprehensively managing the full API lifecycle from design and standardization to documenting, publishing, testing and managing APIs. These tools provide API developers, managers, and users an end-to-end platform for designing, prototyping. Through the platform, users gain the agility needed to support changing business demands and opportunities, while having clear visibility into who is using APIs for better control, security and monetization of digital assets.
[https://cloud.oracle.com/en_US/api-platform/datasheets]

Architecture

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 0

Management Portal:
APIs are managed, secured, and published using the Management Portal.
The Management Portal is hosted on the Oracle Cloud, managed by Oracle, and users granted
API Manager privileges have access.

Gateways:
API Gateways are the runtime components that enforce all policies, but also help in
collecting data for analytics. The gateways can be deployed anywhere – on premise, on Oracle
Cloud or to any third party cloud providers.

Developer Portal:
After an API is published, Application Developers use the Developer Portal to discover, register, and consume APIs. The Developer Portal can be customized to run either on the Oracle Cloud or directly in the customer environment on premises.
[https://cloud.oracle.com/opc/paas/datasheets/APIPCSDataSheet_Jan2018.pdf]

Oracle Apiary:
In my article “Oracle API Platform Cloud Service: Design-First approach and using Oracle Apiary”, I talked about using Oracle Apiary and interacting with its Mock Server for the “HumanResourceService” API, I created earlier.

The Mock Server for the “HumanResourceService” API is listening at:
http://private-b4874b1-humanresourceservice.apiary-mock.com
[https://technology.amis.nl/2018/01/31/oracle-api-platform-cloud-service-design-first-approach-using-oracle-apiary/]

Roles

Within Oracle API Platform CS roles are used.

Roles determine which interfaces a user is authorized to access and the grants they are eligible to receive.
[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/api-platform-cloud-service-roles-resources-actions-and-grants.html]

  • Administrator
    System Administrators responsible for managing the platform settings. Administrators possess the rights of all other roles and are eligible to receive grants for all objects in the system.
  • API Manager
    People responsible for managing the API lifecycle, which includes designing, implementing, and versioning APIs. Also responsible for managing grants and applications, providing API documentation, and monitoring API performance.
  • Application Developer
    API consumers granted self-service access rights to discover and register APIs, view API documentation, and manage applications using the Developer Portal.
  • Gateway Manager
    Operations team members responsible for deploying, registering, and managing gateways. May also manage API deployments to their gateways when issued the Deploy API grant by an API Manager.
  • Gateway Runtime
    This role indicates a service account used to communicate from the gateway to the portal. This role is used exclusively for gateway nodes to communicate with the management service; users assigned this role can’t sign into the Management Portal or the Developer Portal.
  • Service Manager
    People responsible for managing resources that define backend services. This includes managing service accounts and services.
  • Plan Manager
    People responsible for managing plans.

Within the Oracle VM VirtualBox APIPCS appliance the following users (all with password welcome1) are present and used by me in this article:

User Role
api-manager-user APIManager
api-gateway-user GatewayManager
app-dev-user ApplicationDeveloper

Publish an API, via the Management Portal (api-manager-user)

Start the Oracle API Platform Cloud – Management Portal as user api-manager-user.

Navigate to tab “Publication” of the “HumanResourceService” API (which I created earlier).
[https://technology.amis.nl/2018/04/14/oracle-api-platform-cloud-service-using-the-management-portal-and-creating-an-api-including-some-policies/]

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 123

Publish an API to the Developer Portal when you want application developers to discover and consume it.

Each published API has a details page on the Developer Portal. This page displays basic information about the API, an overview describing the purpose of the API, and documentation for using the API. This page is not visible on the Developer Portal until you publish it.
[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/publishing-apis.html#GUID-145F0AAE-872B-4577-ACA6-994616A779F1]

The tab “Publication” contains the following parts:

  • API Portal URL
  • Developer Portal API Overview
  • Documentation

Next I will explain (in reversed order) these parts in more detail.

As you can see, for some of the parts we can use HTML, Markdown or Apiary.

Remark:
Markdown is a lightweight markup language with plain text formatting syntax.
[https://en.wikipedia.org/wiki/Markdown]

Part “Documentation” of the tab “Publication”

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 124c

You can provide HTML or Markdown documentation by uploading a file, manually entering text, or providing a URL to the documentation resource. After you have added the documentation, it appears on the Documentation tab of the API detail page in the Developer Portal.
[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/publishing-apis.html#GUID-9FD22DC2-18A9-4338-91E7-70726C906B91]

It is also possible to add documentation from Oracle Apiary to an API.

Adding documentation to the API can help users understand its purpose and how it was configured.

Note:
Swagger or API Blueprint documentation can only be added to an Oracle Apiary Pro account. To add documentation, the team must have ownership of the API in Oracle Apiary. API definitions owned by personal accounts cannot be used. To transfer ownership of an API from a personal account to a team account, see the Oracle Apiary documentation.
[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/publishing-apis.html#GUID-A7E68AA0-396D-400C-933C-1C4CD3DDD832]

So let’s see how I tried using documentation from Oracle Apiary.

Using Oracle Apiary for documentation

I clicked on button “Apiary”. In my case the following screen appeared:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 125

Next, I clicked on button “Go To Apiary”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 126

Then I clicked on button “Sign in”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 127

After a successful sign in (for example by using Email/Password), the following screen appeared (with the “HumanResourceService” API visible):

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 128

Next, I clicked on button “Create a team”. The following pop-up appeared:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 129

Because I use a Free (personal) Account for Oracle Apiary, I am not able to create a team.

Remember the note (see above) saying: “Swagger or API Blueprint documentation can only be added to an Oracle Apiary Pro account. To add documentation, the team must have ownership of the API in Oracle Apiary. API definitions owned by personal accounts cannot be used.”.
[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/publishing-apis.html#GUID-A7E68AA0-396D-400C-933C-1C4CD3DDD832]

So, for me, the path of using documentation from Oracle Apiary came to an end.

As an alternative, in this article, I used Markdown for documentation. But before explaining that in more detail, I want to give you an impression of screenshot’s of what happens when you click on button “Apiary” and have an Apiary account with the right privileges to add documentation to an API.

Remark:
The screenshot’s that follow, are taken from the API Platform Cloud Service bootcamp, I attended at the Oracle Partner PaaS Summer Camps VII 2017 in Lisbon last year.

So, when you click on button “Apiary”, the following screen appears:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 152

A list of API’s is visible where you can choose one to connect. For example: “TicketService27” API.

After a click on button “Connect”, the “Documentation” part of tab “Publication” looks like:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 153

Using Markdown for documentation

For reasons mentioned above, as an alternative for using Oracle Apiary, in this article, I used Markdown for documentation. Markdown is new to me, so (in this article) I will only demonstrate it with a simplified version of the documentation (available in Apiary).

Click on button “Markdown”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 130

Next, click on tab “Text” and enter the following text:

# HumanResourceService

Human Resource Service is an API to manage Human Resources.

## Employees Collection [/employees]

### Get all employees [GET /employees]

Get all employees.

### Get an employee [GET /employees/{id}]

Get a particular employee by providing an identifier.

### Create an employee [POST /employees]

Create an employee, by using post with the complete payload.

### Update an employee [PUT /employees/{id}]

Update an employee, by using put with the a payload containing: last_name, job_id, salary and department_id.

## Departments Collection [/departments]

### Get a department [GET /department/{id}]

Get a particular department by providing an identifier.

### Get a department and employee [GET /departments/{department_id}/employees/{employee_id}]

Get a particular department by providing a department identifier and a particular employee within that department by providing an employee identifier.

After a click on button “OK”, the “Documentation” part of tab “Publication” looks like:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 132

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 136

In the pop-up, click on button “Save Changes”.

Part “Developer Portal API Overview” of the tab “Publication”

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 124b

You can provide overview text for an API, describing its features and other information a developer should know about its use, in either HTML or Markdown.

You can upload a file, enter text manually, or provide a link to HTML or Markdown to use as overview text. This text appears on the API’s detail page in the Developer Portal.
[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/publishing-apis.html#GUID-D1BF7E3E-03C9-42AE-9808-EC9BC77D3E61]

For the “Developer Portal API Overview” part, I chose to use HTML (because in this article, up to now, examples of using Markdown and Apiary were already provided).

Once again I will only demonstrate it with a simplified version of the documentation (available in Apiary).

Click on button “HTML”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 134

Next, click on tab “Text” and enter the following text:

<h1>HumanResourceService</h1>

Human Resource Service is an API to manage Human Resources.

It provides CRUD methods for the resources <b>Employees</b> and <b>Departments</b>.

After a click on button “OK”, the “Developer Portal API Overview” part of tab “Publication” looks like:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 135

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 136

In the pop-up, click on button “Save Changes”.

Part “API Portal URL” of the tab “Publication”

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 124a

Before publishing to the Developer Portal, each API has to be configured with its own unique Vanity Name. A vanity name is the URI path of an API’s details page when it is published to the Developer Portal.

On the Publication tab, enter the path at which this API will be discoverable in the Developer Portal in the API Portal URL field. This is also called the API’s vanity name.

Note:
An API’s vanity name must be unique, regardless of case. You can’t have APIs with vanity names of Creditcheck and creditcheck. You must enter the vanity name exactly (matching case) in the URL to navigate to an API’s details page in the Developer Portal. For example, navigating to https://<host>:<port>/developers/apis/Creditcheck opens the page for an API with a vanity name of Creditcheck; https://<host>:<port>/developers/apis/creditcheck doesn’t open this page and returns a 404 because the segment in the URL does not match the vanity name exactly.

Only valid URI simple path names are supported. Characters such as “?”, “/”, and “&” are not supported in vanity names. Test_2 is a supported vanity name, but Test/2 is not.
[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/publishing-apis.html#GUID-C9034B10-72EA-4046-A8B8-B5B1AE087180]

The default API’s vanity name, is derived from the API name:

<not published>/HumanResourceService

Publish the “HumanResourceService” API to the Developer Portal

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 137

So now that we have all the documentation in place, Notice that the button “Preview” appeared.

Clicking on button “Preview” generates an error:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 139

Remember that I am using a demo environment of Oracle API Platform CS by using the Oracle VM VirtualBox APIPCS appliance. This seems to be a bug in that environment. So what should have been visible was something like:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 143a

Here you can see on the left, that the tab “Overview” is selected . There is also a tab “Documentation”.

Remark:
Please see the screenshot’s later on in this article for the “HumanResourceService”API in the “Developer Portal” (tab APIs), with regard to the tabs “Overview” and “Documentation”. These show the same information as in the Preview context.

Next, click on button “Publish to Portal”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 140

Notice that the > icon “Launch Developer Portal in another browser window” appeared and also that the API Portal URL is changed to:

http://apics.oracle.com:7201/developers/apis/HumanResourceService

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 205

In the top part of the screen you can see that the “HumanResourceService”API is “Published’.

It’s time to launch the Developer Portal.

Click on the icon “Launch Developer Portal in another browser window”.

Sign in to the Oracle API Platform Cloud – Developer Portal as user app-dev-user

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 142

After a successful sign in as user app-dev-user, the next screen appears (with tab “APIs” selected):

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 148

The “Developer Portal” is the web page where you discover APIs, subscribe to APIs and get the necessary information to invoke them. When you access the “Developer Portal”, the API Catalog page appears. All the APIs that have been published to the “Developer Portal” are listed. Use the API Catalog page to find APIs published to the “Developer Portal”.

In the “Developer Portal” screen above there are no APIs, or they are not visible for the current user. So we have to go back to the Oracle API Platform Cloud – Management Portal (as an API Manager). There we can grant the privileges needed for an Application Developer to see the API. How you do this is described later on in this article.

For now we continue as if the correct privileges were already in place. Therefor the “HumanResourceService” API is visible.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 159

Click on the “HumanResourceService” API.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 143

Here you can see on the left, that the tab “Overview” is selected.

For now I will give you a short overview of screenshot’s of each of the tabs on the left.

Tab “Overview” of the “HumanResourceService” API

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 146

Remember that we used HTML code for the “Developer Portal API Overview” part of the tab “Publication”?
So here you can see the result.

Tab “Documentation” of the “HumanResourceService” API

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 147

Remember that we used Markdown code for the “Documentation” part of the tab “Publication”?
So here you can see the result.

Remark:
If I had an Apiary account with the right privileges to add documentation to an API and used Apiary for documentation, the tab “Documentation” would have looked like:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 149

Discover APIs

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 159

In the API Catalog page, you can search for an API by entering keywords in the field at the top of the catalog. The list is narrowed to the APIs that have that word in the name or the description. If you enter multiple words, the list contains all APIs with either of the words; APIs with both words appear at the top of the list. If a keyword or keywords have been applied to the list, they appear in a bar at the top of the page. Filters can also be applied to the list. You can also sort the list for example in alphabetical order or by newest to oldest API.
[Oracle Partner PaaS Summer Camps VII 2017, APIPCS bootcamp, Lab_APIPCS_Design_and_Implement.pdf]

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 160

Subscribe an application to the “HumanResourceService” API

In the “Developer Portal” screen if we navigate, in the API Catalog page, to the “HumanResourceService” API, and if the user has the correct privileges, a button “Subscribe” is visible. In the Oracle API Platform Cloud – Management Portal (as an API Manager) we can grant the privileges needed for an Application Developer to register an application to the API. How you do this is described later on in this article.

For now we continue as if the correct privileges were already in place.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 164

Click on button “Subscribe”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 165

Next, click on button “Create New Application”. Enter the following values:

Application Name HumanResourceWebApplication
Description Web Application to manage Human Resources.
Application Types Web Application
Contact information:
First Name FirstName
Last Name LastName
Email Email@company.com
Phone 123456789
Company Company

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 166

Click on button “Save”.

For a short while a pop-up “The application ‘HumanResourceWebApplication’ was created.” appears.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 168

So now we have an application, we can subscribe it, to the “HumanResourceService” API.

Notice that an Application Key was generated, with as value:

fb3138d1-0636-456e-96c4-4e21b684f45e

Remark:
You can reissue a key for an application in case it has been compromised, Application keys are established at the application level. If you reissue an application’s key, the old key is invalidated. This affects all APIs (that have the key validation policy applied) to which an application is registered. Every request to these APIs must use the new key to succeed. Requests using the old key are rejected. APIs without the key validation policy are not affected as these do not require a valid application key to pass requests.
[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/reissuing-application-key.html#GUID-4E570C15-C289-4B6D-870C-F7ADACC1F6DD]

Next, click on button “Subscribe API”.

For a short while a pop-up “API ‘HumanResourceService’ was subscribed to application ‘HumanResourceWebApplication’.” appears.

A request to register the application to the API is sent to the API Manager. So now we have to wait for the approval of the API Manager. How you do this is described later on in this article.

In the API Catalog page, when viewing an API you can see which applications are subscribed to it.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 173

In the My Applications page, when viewing an application you can see which APIs it subscribed to.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 174

After a click on the “HumanResourceWebApplication” application, the next screen appears (with tab “Overview” selected):

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 176

First l will give you a short overview of screenshot’s of each of the tabs on the left. Some of these I will explain in more detail as I will walk you through some of the functionality of Oracle API Platform CS.

Tab “Overview” of the “HumanResourceWebApplication” application

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 177

Tab “Subscribed APIs” of the “HumanResourceWebApplication” application

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 178

Tab “Grants” of the “HumanResourceWebApplication” application

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 179

Application grants are issued per application.

The following tabs are visible and can be chosen:

  • Manage Application
    People issued this grant can view, modify and delete this application. API Manager users issued this grant can also issue grants for this application to others.
  • View all details
    People issued this grant can see all details about this application in the Developer Portal.

See for more information: https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/managing-application-grants.html

Tab “Analytics” of the “HumanResourceWebApplication” application

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 180

Create an Application in the “My Applications” page

Click on button “New Application”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 183

In the same way as described before I created several applications (one at a time) with minimum information (Application Name, Application Types, First Name, Last Name and Email).

In the My Applications page, the list of applications then looks like:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 182

In the table below I summarized the applications that I created:

Application Name Application Types Application Key
DesktopApp_A_Application Desktop App e194833d-d5ac-4c9d-8143-4cf3a3e81fea
DesktopApp_B_Application Desktop App fd06c3b5-ab76-4e89-8c5a-e4b8326c360b
HumanResourceWebApplication Web Application fb3138d1-0636-456e-96c4-4e21b684f45e
MobileAndroid_A_Application Mobile – Android fa2ed56f-da3f-49ea-8044-b16d9ca75087
MobileAndroid_B_Application Mobile – Android 385871a2-7bb8-4281-9a54-c0319029e691
Mobile_iOS_A_Application Mobile – iOS 7ebb4cf8-5a3f-4df5-82ad-fe09850f0e50

In the API Catalog page, navigate to the “HumanResourceService” API. Here you can see that there is already one subscribed application.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 184

Click on button “Subscribe”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 185

Next, select the “MobileAndroid_B_Application” application.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 186

For a short while a pop-up “API ‘HumanResourceService’ was subscribed to application ‘ MobileAndroid_B_Application ‘.” appears.

In the API Catalog page, when viewing an API you can see which applications are subscribed to it.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 188

Here we can see the status “Pending”. A request to register the “MobileAndroid_B_Application” application to the “HumanResourceService” API is sent to the API Manager. So now we have to wait for the approval of the API Manager. Repeat the steps described in this article, to approve the request, by switching to an API Manager.

In the screen below, we can see the end result:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 190

Edit the Key Validation Policy, via the Management Portal (api-manager-user)

In the top right of the Oracle API Platform Cloud – Management Portal sign in as user api-manager-user.

Navigate to tab “API Implementation” of the “HumanResourceService” API.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 191

Hoover over the “Key Validation” policy and then, on the right, click on icon “Edit policy details”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 192

Click on button “Apply”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 193

Next, click on button “Save Changes”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 194

I applied this policy as an active policy, represented as a solid line around the policy.

Redeploy the API, via the Management Portal (api-manager-user)

Navigate to tab “Deployments” of the “HumanResourceService” API, and then hover over the “Production Gateway” gateway and then, on the right, hover over the icon “Redeploy”.

Next, click on icon “Latest Iteration”. Also approve the request, by switching to a Gateway Manager.
How you do this, is described in my previous article “Oracle API Platform Cloud Service: using the Management Portal and creating an API (including some policies)”.
[https://technology.amis.nl/2018/04/14/oracle-api-platform-cloud-service-using-the-management-portal-and-creating-an-api-including-some-policies/]

So now the “HumanResourceService” API is redeployed on the “Production Gateway” gateway (Node 1).

It is time to invoke the API.

Validating the “Key Validation” policy, via Postman

As described in my previous article, in Postman, I created requests within the collection named “HumanResourceServiceCollection”.
[https://technology.amis.nl/2018/04/14/oracle-api-platform-cloud-service-using-the-management-portal-and-creating-an-api-including-some-policies/]

Then again I invoked two request, to validate them against the “Key Validation” policy.

Invoke method “GetEmployee” of the “HumanResourceService” API

From Postman I invoked the request named “GetEmployeeRequest” (with method “GET” and URL “http://apics.oracle.com:8001/HumanResourceService/1/employees/100”) and a response with “Status 401 Unauthorized” is shown:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 195

After providing the Value fb3138d1-0636-456e-96c4-4e21b684f45e (being the Application Key of the “HumanResourceWebApplication” application) for the Header Key “application-key”, a response with “Status 200 OK” is shown:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 196

After providing the Value e194833d-d5ac-4c9d-8143-4cf3a3e81fea (being the Application Key of the “DesktopApp_A_Application” application) for the Header Key “application-key”, a response with “Status 401 Unauthorized” is shown:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 197

Invoke method “GetDepartmentEmployee” of the “HumanResourceService” API

From Postman I invoked the request named “GetDepartmentEmployeeRequest” (with method “GET” and URL “http://apics.oracle.com:8001/HumanResourceService/1/departments/30/employees/119”) and a response with “Status 401 Unauthorized” is shown:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 198

After providing the Value 385871a2-7bb8-4281-9a54-c0319029e691 (being the Application Key of the “MobileAndroid_B_Application” application) for the Header Key “application-key”, a response with “Status 200 OK” is shown:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 199

Tab “Analytics” of the “Production Gateway” gateway

In the top right of the Oracle API Platform Cloud – Management Portal sign in as user api-gateway-user and click on the “Production Gateway” gateway and navigate to the tab “Analytics”.

In this tab the requests I sent, are visible at “Total Requests”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 200

If we look, for example, at “Requests By Resource”, the requests are also visible.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 201

Next, click on icon “Applications (4 Active)” and if we look, for example, at “Active Applications”, we can see that there were in total 3 request rejections (because of policy “Key Validation”).

If we look, for example, at “Requests By API”, the requests are also visible.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 203

There were 2 request that had no Header Key “application-key” at all. As you can see in the graph above, these were rejected and were administrated under “Unknown Application (No Key).

There was 1 request that had a Value e194833d-d5ac-4c9d-8143-4cf3a3e81fea for the Header Key “application-key”. As you can see in the graph above, this request was rejected and was administrated under the “DesktopApp_A_Application” application. Remember that this application was not registered to the “HumanResourceService” API.

The other 2 request were accepted, because they had a valid Value for the Header Key and the corresponding applications were registered to the “HumanResourceService” API.

So the “Key Validation” policy is working correct.

Sign in to the Oracle API Platform Cloud – Management Portal as user api-manager-user

Go back to the Oracle API Platform Cloud – Management Portal and, if not already done, sign in as user api-manager-user. Navigate to tab “Grants” of the “HumanResourceService” API.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 155

API grants are issued per API.

The following tabs are visible and can be chosen:

  • Manage API
    Users issued this grant are allowed to modify the definition of and issue grants for this API.
  • View all details
    Users issued this grant are allowed to view all information about this API in the Management Portal.
  • Deploy API
    Users issued this grant are allowed to deploy or undeploy this API to a gateway for which they have deploy rights. This allows users to deploy this API without first receiving a request from an API Manager.
  • View public details
    Users issued this grant are allowed to view the publicly available details of this API on the Developer Portal.
  • Register
    Users issued this grant are allowed to register applications for this plan.
  • Request registration
    Users issued this grant are allowed to request to register applications for this plan.

Users and groups issued grants for a specific API have the privileges to perform the associated actions on that API. See for more information: https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/managing-api-grants.html.

“View public details” grant

To view an API, the Application Developer must have the “View public details” grant or another grant that implies these privileges.

Click on tab “View public details”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 156

Next, click on button “Add Grantee”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 157

Select “app-dev-user” and click on button “Add”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 158

So now, the user app-dev-user (with Role ApplicationDeveloper) is granted the “View public details” privilege.

Remark:
In practice you would probably grant to a group instead of to a single user.

“Request registration” grant

To register an API, the Application Developer must have the “Request registration” grant or another grant that implies these privileges.

Click on tab “Request registration”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 161

Next, click on button “Add Grantee”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 162

Select “app-dev-user” and click on button “Add”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 163

So now, the user app-dev-user (with Role ApplicationDeveloper) is granted the “Request registration” privilege.

Remark:
In practice you would probably grant to a group instead of to a single user.

Be aware that you could also grant the “Register” privilege, so approval of the API Manager (for registering an application to an API) is not needed anymore in that case. This makes sense if it concerns a development environment, for example. Since the Oracle VM VirtualBox APIPCS appliance is using a “Production Gateway” gateway, in this article, I chose for the request and approve mechanism.

Approve a request for registering an application to an API, via the Management Portal (api-manager-user)

On the left, click on tab “Registrations” and then click on tab “Requesting”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 169

Hover over the “HumanResourceWebApplication” application, then click on button “Approve”.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 170

In the pop-up, click on button “Yes”.

Then you can see on the tab “Registered”, that the registration is done.

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 171

After a click on the top right icon “Expand”, more details are shown:

Oracle API Platform Cloud Service: using the Developer Portal for discovering APIs via the API Catalog and subscribing applications to APIs lameriks 201804 172

So now the “HumanResourceWebApplication” application is registered to the “HumanResourceService” API.

Summary

As a follow up from my previous articles about Oracle API Platform Cloud Service, in this article the focus is on using the Developer Portal, discovering APIs via the API Catalog and subscribing applications to APIs.

I activated the Key Validation (Security) policy, which I created in my previous article, and redeployed the API to a gateway and validated that this policy worked correct, using requests which I created in Postman.
[https://technology.amis.nl/2018/04/14/oracle-api-platform-cloud-service-using-the-management-portal-and-creating-an-api-including-some-policies/]

While using the Management Portal and Developer Portal in this article, I focused on the roles “API Manager” and “Application Developer”. For example, the user api-manager-user had to approve a request from the app-dev-user to register an application to an API.

At the API Platform Cloud Service bootcamp (at the Oracle Partner PaaS Summer Camps VII 2017 in Lisbon last year, at the end of august), I (and many others) got hands-on experience with the API Platform Cloud Service. There we created an API with more policies than described in this article.

It became obvious that the API Platform Cloud Service is a great API Management solution and that with the help of policies your are able to secure, throttle, route, manipulate, or log requests before they reach the backend service.