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 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
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 |
Design-First approach
Design is critical as a first step for great APIs. Collaboration ensures that we are creating the correct design. In my previous article “Oracle API Platform Cloud Service: Design-First approach and using Oracle Apiary”, I talked about the Design-First approach and using Oracle Apiary. I designed a “HumanResourceService” API.
[https://technology.amis.nl/2018/01/31/oracle-api-platform-cloud-service-design-first-approach-using-oracle-apiary/]
So with a design in place, an application developer could begin working on the front-end, while service developers work on the back-end implementation and others can work on the API implementation, all in parallel.
Create an API, via the Management Portal (api-manager-user)
Start the Oracle API Platform Cloud – Management Portal as user api-manager-user.
After a successful sign in, the “APIs” screen is visible.
Create a new API via a click on button “Create API”. Enter the following values:
| Name | HumanResourceService |
| Version | 1 |
| Description | Human Resource Service is an API to manage Human Resources. |
Next, click on button “Create”.
After a click on the “HumanResourceService” API, the next screen appears (with tab “APIs” selected):
Here you can see on the left, that the tab “API Implementation” is selected.
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 “API Implementation” of the “HumanResourceService” API
Tab “Deployments” of the “HumanResourceService” API
Tab “Publication” of the “HumanResourceService” API
Tab “Grants” of the “HumanResourceService” API
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.
Tab “Registrations” of the “HumanResourceService” API
Tab “Analytics” of the “HumanResourceService” API
Tab “API Implementation” of the “HumanResourceService” API
After you create an API, you can apply policies to configure the Request and Response flows. Policies in the Request flow secure, throttle, route, manipulate, or log requests before they reach the backend service. Polices in the Response flow manipulate and log responses before they reach the requesting client.
[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/implementing-apis.html]
Request flow, configuring the API Request URL
The API Request URL is the endpoint to which users or applications send requests for your API. You configure part of this URL. This endpoint resides on the gateway on which the API is deployed. The API will be deployed later.
The full address to which requests are sent consists of the protocol used, the gateway hostname, the API Request endpoint, and any private resource paths available for your service.
<protocol>://<hostname and port of the gateway node instance>/<API Request endpoint>/<private resource path of the API>
Anything beyond the API Request endpoint is passed to the backend service.
Hover over the “API Request” policy and then, on the right, click the icon “Edit policy details”. Enter the following values:
| Your Policy Name | API Request |
| Comments | |
| Configuration | Protocol | HTTP |
| ://MyGatewayIP/ | |
| Configuration | API Endpoint URL | HumanResourceService/1 |
Next, click on button “Apply”.
In the pop-up, click on button “Save Changes”.
Request flow, configuring the Service Request URL
The Service Request is the URL at which your backend service receives requests.
When a request meets all policy conditions, the gateway routes the request to this URL and calls your service. Note that the Service Request URL can point to any of your service’s resources, not just its base URL. This way you can restrict users to access only a subset of your API’s resources.
Hover over the “Service Request” policy and then, on the right, click the icon “Edit policy details”. Enter the following values:
| Configure Headers | – |
| Service | Enter a URL | <Enter the Apiary Mock Service URL>
For example: Remark: |
| Use Gateway Node Proxy | uncheck |
| Service Account | None |
Next, click on button “Apply”.
In the pop-up, click on button “Save Changes”.
Oftentimes, there are multiple teams participating in the development process. There may be front-end developers creating a new mobile app or chatbot, there can be a backend services and integration team and of course the API team.
If the backend service is not yet ready, you can still start creating the API. Perhaps you may want to begin with a basic implementation (for example an Apiary Mock Service URL) so your front-end developers are already pointing to the API, even before it is fully operational.
Response Flow
Click the Response tab to view a top-down visual representation of the response flow. The Service and API Response entries can’t be edited.
The Service Response happens first. The response from the backend service is always the first entry in the outbound flow. You can place additional policies in this flow. Policies are run in order, with the uppermost policy run first, followed by the next policy, and so on, until the response is sent back to the client.
The API Response entry is a visual representation of the point in the outbound flow when the response is returned to the requesting client.
[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/implementing-apis.html]
Deploy an API to the Gateway, via the Management Portal (api-manager-user)
On the left, click on tab “Deployments”.
Next, click on button “Deploy API”.
In the pop-up “Deploy API” there are no gateways, or they are not visible for the current user. So in order to find out what the situation is about the gateways, we have to sign in, in the Oracle API Platform Cloud – Management Portal as a Gateway Manager. There we also can grant the privileges needed to deploy 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.
So in the pop-up “Deploy API”, select the “Production Gateway” gateway and click on button ‘Deploy”.
For a short while a pop-up “Deployment request submitted” appears.
Next, click on tab “Requesting” where we can see the request (for an API deployment to a gateway), the user api-manager-user sent to the Gateway Manager. The “Deployment State” is REQUESTING. So now we have to wait for the approval of the Gateway Manager.
Sign in to the Oracle API Platform Cloud – Management Portal as user api-gateway-user
In the top right of the Oracle API Platform Cloud – Management Portal click on the api-manager-user and select ”Sign Out”. Next, Sign in as user api-gateway-user.
After a successful sign in, the “Gateways” screen is visible.
Because this user is only a Gateway Manager, only the tab “Gateways” is visible.
At the moment (in this demo environment) there is one gateway available, being the “Production Gateway”. After a click on the “Production Gateway” gateway, the next screen appears:
Here you can see on the left, that the tab “Settings” is selected.
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 “Settings” of the “Production Gateway” gateway
Have a look at the “Load Balancer URL” (http://apics.oracle.com:8001), which we will be using later on in this article.
Tab “Nodes” of the “Production Gateway” gateway
Tab “Deployments” of the “Production Gateway” gateway
Tab “Grants” of the “Production Gateway” gateway
Tab “Analytics” of the “Production Gateway” gateway
Tab “Grants” of the “Production Gateway” gateway
On the left, click on tab “Grants”.
Grants are issued per gateway.
The following tabs are visible and can be chosen:
- Manage Gateway
Users issued this grant are allowed to manage API deployments to this gateway and manage the gateway itself.Remark:
The api-gateway-user (with role GatewayManager) is granted the “Manage Gateway” privilege. - View all details
Users issued this grant are allowed to view all information about this gateway. - Deploy to Gateway
Users issued this grant are allowed to deploy or undeploy APIs to this gateway. - Request Deployment to Gateway
Users issued this grant are allowed to request API deployments to this gateway. - Node service account
Gateway Runtime service accounts are issued this grant to allow them to download configuration and upload statistics.
Users issued grants for a specific gateway have the privileges to perform the associated actions on that gateway. See for more information: https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/managing-gateway-grants.html.
Click on tab “Request Deployment to Gateway”.
Next, click on button “Add Grantee”.
Select “api-manager-user” and click on button “Add”.
So now, the user api-manager-user (with Role APIManager) is granted the “Request Deployment to Gateway” 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 “Deploy to Gateway” privilege, so approval of the Gateway Manager (for deploying an API to a gateway) 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 an API deployment to a gateway, via the Management Portal (api-gateway-user)
On the left, click on tab “Deployments” and then click on tab “Requesting”.
Hover over the “HumanResourceService” API, then click on button “Approve”.
In the pop-up, click on button “Yes”.
Then you can see that on the tab “Waiting”, the deployment is waiting.
Remark:
The deployment enters a Waiting state and the logical gateway definition is updated. The endpoint is deployed the next time gateway node(s) poll the management server for the updated gateway definition.
So after a short while, you can see on the tab “Deployed”, that the deployment is done.
After a click on the top right icon “Expand”, more details are shown:
So now the “HumanResourceService” API is deployed on the “Production Gateway” gateway (Node 1). We can also see the active policies in the Request and Response flow of the API Implementation.
It is time to invoke the API.
Invoke method “GetAllEmployees” of the “HumanResourceService” API, via Postman
For invoking the “HumanResourceService” API I used Postman (https://www.getpostman.com) as a REST Client tool.
In Postman, I created a collection named “HumanResourceServiceCollection”(in order to bundle several requests) and created a request named “GetAllEmployeesRequest”, providing method “GET” and request URL “http://apics.oracle.com:8001/HumanResourceService/1/employees”.
Remember the “API Request URL”, I configured partly in the “API Request” policy and the “Load Balancer URL” of the “Production Gateway” gateway? They make up the full address to which requests have to be sent.
After clicking on button Send, a response with “Status 200 OK” is shown:
Because I have not applied any extra policies, the request is passed to the backend service without further validation. This is simply the “proxy pattern”.
Later on in this article, I will add some policies and send additional requests to validate each one of them.
Tab “Analytics” of the “Production Gateway” gateway
Go back to the Management Portal (api-gateway-user) and in the tab “Analytics” the request I sent, is visible at “Total Requests”.
If we look, for example, at “Requests By Resource”, the request is also visible.
Policies
Policies in API Platform CS serve a number of purposes. You can apply any number of policies to an API definition to secure, throttle, limit traffic, route, or log requests sent to your API. Depending on the policies applied, requests can be rejected if they do not meet criteria you specify when configuring each policy. Policies are run in the order they appear on the Request and Response tabs. A policy can be placed only in certain locations in the execution flow.
The available policies are:
Security:
- OAuth 2.0 | 1.0
- Key Validation | 1.0
- Basic Auth | 1.0
- Service Level Auth | 1.0 Deprecated
- IP Filter Validation | 1.0
- CORS | 1.0
Traffic Management:
- API Throttling – Delay | 1.0
- Application Rate Limiting | 1.0
- API Rate Limiting | 1.0
Interface Management:
- Interface Filtering | 1.0
- Redaction | 1.0
- Header Validation | 1.0
- Method Mapping | 1.0
Routing:
- Header Based Routing | 1.0
- Application Based Routing | 1.0
- Gateway Based Routing | 1.0
- Resource Based Routing | 1.0
Other:
- Service Callout | 2.0
- Service Callout | 1.0
- Logging | 1.0
- Groovy Script | 1.0
As an example I have created two policies: Key Validation (Security) and Interface Filtering (Interface Management).
Add a Key Validation Policy, via the Management Portal (api-manager-user)
Use a key validation policy when you want to reject requests from unregistered (anonymous) applications.
Keys are distributed to clients when they register to use an API on the Developer Portal. At runtime, if they key is not present in the given header or query parameter, or if the application is not registered, the request is rejected; the client receives a 400 Bad Request error if no key validation header or query parameter is passed or a 403 Forbidden error if an invalid key is passed.
[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/implementing-apis.html#GUID-5CBFE528-A74E-4700-896E-154378818E3A]
This policy requires that you create and register an application, which is described in my next article.
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, and then in the “Available Policies” region, expand “Security”. Hover over the “Key Validation” policy and then, on the right, click the icon “Apply”. Enter the following values:
| Your Policy Name | Key Validation |
| Comments | |
| Place after the following policy | API Request |
Then, click on icon “Next”. Enter the following values:
| Key Delivery Approach | Header |
| Key Header | application-key |
Click on button “Apply as Draft”.
Next, click on button “Save Changes”.
I applied this as a draft policy, represented as a dashed line around the policy. Draft policies let you “think through” what you want before you have the complete implementation details. This enables you to complete the bigger picture in one sitting and to leave reminders of what is missing to complete the API later.
When you deploy an API, draft policies are not deployed.
Add an Interface Filtering Policy, via the Management Portal (api-manager-user)
Use an interface filtering policy to filter requests based on the resources and methods specified in the request.
[https://docs.oracle.com/en/cloud/paas/api-platform-cloud/apfad/implementing-apis.html#GUID-69B7BC21-416B-4262-9CE2-9896DEDF2144]
Navigate to tab “API Implementation” of the “HumanResourceService” API, and then in the “Available Policies” region, expand “Interface Management”. Hover over the “Interface Filtering” policy and then, on the right, click the icon “Apply”. Enter the following values:
| Your Policy Name | Interface Filtering |
| Comments | |
| Place after the following policy | Key Validation |
Then, click on icon “Next”.
In the table below I summarized the requests that I created in the Oracle Apiary Mock Server for the “HumanResourceService” API:
| Request name | Method | Oracle Apiary Mock Server Request URL |
| GetAllEmployeesRequest | GET | http://private-b4874b1-humanresourceservice.apiary-mock.com/employees |
| CreateEmployeeRequest | POST | http://private-b4874b1-humanresourceservice.apiary-mock.com/employees |
| GetEmployeeRequest | GET | http://private-b4874b1-humanresourceservice.apiary-mock.com/employees/100 |
| UpdateEmployeeRequest | PUT | http://private-b4874b1-humanresourceservice.apiary-mock.com/employees/219 |
| GetDepartmentRequest | GET | http://private-b4874b1-humanresourceservice.apiary-mock.com/departments/30 |
| GetDepartmentEmployeeRequest | GET | http://private-b4874b1-humanresourceservice.apiary-mock.com/departments/30/employees/119 |
I want to use an interface filtering policy to filter requests. As an example, I want to pass requests (to the backend service) with the method GET specified in the request and a resource starting with employees followed by an identification or starting with departments followed by employees and an identification.
Select “Pass” from the list.
At “Filtering Conditions”, “Condition 1” enter the following values:
| Resources | /employees/* ; /departments/*/employees* |
| Methods | GET |
Click on button “Apply ”.
Next, click on button “Save Changes”.
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”.
In the pop-up, click on button “Yes”. For a short while a pop-up “Redeploy request submitted” appears.
Then repeat the steps described before in this article, to approve the request, by switching to a Gateway Manager.
Remark:
Click on “Latest Iteration” to deploy the most recently saved iteration of the API.
Click on “Current Iteration” to redeploy the currently deployed iteration of the API.
After that, it is time to try out the effect of adding the “Interface Filtering” policy.
Validating the “Interface Filtering” policy, via Postman
In Postman for each request mentioned earlier (in the table), I created that request within the collection named “HumanResourceServiceCollection”.
Then again I invoked each request, to validate it against the “Interface Filtering” policy.
Invoke method “GetAllEmployees” of the “HumanResourceService” API
From Postman I invoked the request named “GetAllEmployeesRequest” (with method “GET” and URL “http://apics.oracle.com:8001/HumanResourceService/1/employees”) and a response with “Status 405 Method Not Allowed” is shown:
Invoke method “CreateEmployee” of the “HumanResourceService” API
From Postman I invoked the request named “CreateEmployeeRequest” (with method “POST” and URL “http://apics.oracle.com:8001/HumanResourceService/1/employees”) and a response with “Status 405 Method Not Allowed” is shown:
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 200 OK” is shown:
Invoke method “UpdateEmployee” of the “HumanResourceService” API
From Postman I invoked the request named “UpdateEmployeeRequest” (with method “PUT” and URL “http://apics.oracle.com:8001/HumanResourceService/1/employees/219”) and a response with “Status 405 Method Not Allowed” is shown:
Invoke method “GetDepartment” of the “HumanResourceService” API
From Postman I invoked the request named “GetDepartmentRequest” (with method “GET” and URL “http://apics.oracle.com:8001/HumanResourceService/1/departments/30”) and a response with “Status 405 Method Not Allowed” is shown:
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 200 OK” is shown:
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”.
If we look, for example, at “Requests By Resource”, the requests are also visible.
Next, click on icon “Error and Rejections (4 Total)” and if we look, for example, at “Rejection Distribution”, we can see that there were 4 request rejections, because of policy “Interface Filtering”.
So the “Interface Filtering” policy is working correct.
Summary
As a follow up from my previous articles about Oracle API Platform Cloud Service, in this article the focus is on using the Management Portal and Creating the “HumanResourceService” API (including some policies).
As an example I have created two policies: Key Validation (Security) and Interface Filtering (Interface Management). The later policy, I deployed to a gateway and validated that this policy worked correct, using requests which I created in Postman.
While using the Management Portal in this article, I focused on the roles “API Manager” and “Gateway Manager”. For example, the user api-gateway-user had to approve a request from the api-manager-user to deploy an API the a gateway.
In a next article the focus will be on validating the “Key Validation” policy and using the “Development Portal”.
Very nice blog post Marc.