Much has been written on RedThunder.blog about the Oracle API Platform Cloud Service. In this blog, I am going to get into the advanced topic of Custom Policies. You would start exploring this area when the built-in policies do not cover your use case. The power and ease of implementing Custom Policies, I believe, is a killer value proposition of this platform.

Before we proceed, it would helpful to understand the backend technology of what the API Platform is built on. API Platform built-on the heritage of the sturdy and scalable WebLogic server.

There are 3 components:

• Management Portal – Used to create and manage APIs. This is an application hosted in WebLogic server, utilising WebLogic for clustering and scaling. Oracle hosts and manages this in our Public Cloud and automates the whole installation process, so you just have a make a few clicks to provision it. The Management Portal is the brains of the API Platform, registering Gateways and deploying and publishing APIs to the Gateways and Developer Portal. You can access all its functions through REST API.
• Gateway Node – Holds the run-time of the API. This is based on the Oracle Communications Service Gatekeeper (OCSG) from our telco-grade suite of products. Built-on WebLogic, the Gateway Nodes can be installed on any platform on-premise or in the Cloud (e.g. Amazon, Azure, Oracle). It is packaged as a zip file downloaded from the Management Portal itself. Once installed, the Gateway calls home to the Management Server to register itself. It pulls APIs and the policies associated with it from the Cloud once they are deployed. Gateways forms a logical cluster for HA purposes, so you deploy once and the APIs propagate to all the nodes in the cluster.

The Gateway Install zip also hosts the necessary code nuggets for customisation.

• Developer Portal – Used for developers to review documentation and subscribe to APIs. Also an application, this is by default hosted in the same WebLogic Server as the Management Portal. If you wish to run another Developer Portal, let’s say on-premise or customise it, you can extract the Developer Portal war from the Gateway Server install zip and host it in another WebLogic server.

Now coming to Custom Policies, they are essentially Java-code packaged as war files. The Gateway Install zip holds the code nuggets necessary to generate a Policy Stub. It also holds the necessary libraries aka Policy SDK (matching the version of the Gateway server) to compile against.

Install the Policy SDK

First install a Gateway Node. Manish Gupta has written a great blog on the install process.

Make sure you have the latest version of JDK (Java 8) and Python 3+ installed.

SSH into the Gateway Node and copy out these files into your SDK directory:

• From /GATEWAY_HOME/ocsg/httpclient/
  • groovy-all.jar
• From /domain/gateway1/servers/ managedServer1/tmp/_WL_user/SharedSDK/{custom folder}/APPINF/lib
  • apiplatform.policies.sdk.jar
  • apiplatform.shared.jar
  • apiplatform.utils.jar
  • json-20160212.jar

Create a Policy Stub

Then crack open the Gateway Zip file, you will find a zip file /policyTemplate/PolicyTemplate.zip.

To create your Policy Stub run:

python PolicyTemplate.py -p {POLICY_NAME} -t {TARGET_DIRECTORY) -s {POLICY_SDK_FOLDER}

Note: This blog is written about API Platform version 18.1.5. You can still create Custom Policies for 18.1.3, however there is no PolicyTemplate.zip inside and you would have to grab it from our Examples Git here:

Explaining the Policy Stub

The stub is formatted for Eclipse, so for easier development you can simply import it in. However, you can also just use a text editor like Atom to modify the code and build on the Command line using Ant. An Ant script is included so no need to write this from scratch.

Let’s look in more detail in a TestPolicy stub we’ve just created.

metadata.json

{policy_name}-edit.html

Oracle JavaScript Extension Toolkit (JET) empowers developers by providing a modular open source toolkit based on modern JavaScript, CSS3 and HTML5 design and development principles.

See the Cookbook for more components.

{policy_name}Runtime.java

More functions can be found in the Java Docs: https://docs.oracle.com/en/cloud/paas/api-platform-cloud/api-platform-javadoc/toc.htm

Building and Deploying the Policy

Now that you’re happy hacking away at your policy, let’s build it and deploy to the Management Portal.

Policies are packaged as jar files and to bring it up to the Management Portal you run a curl script to upload the jar through REST API.

Note that you don’t have to deploy this policy separately for each Gateway. The Management Server is the brains of API Platform and the Gateways poll the Management Server regularly for updates, the policy once attached to an API will be pull down and attached to the Gateway.

An Ant build.xml script and a build.properties file is automatically generated by the Policy Stub. The build.xml script compiles the code into a single jar.

Build using: ant

You should get a file oracle.apiplatform.policies.{your_policy_name}.jar

Now if you’ve followed exactly what I have described above, there appears to a bug in a Policy Stub in which {policy_name}Runtime.java extends BasePolicyRuntime and implements {policy_name}Constants. Checking the JavaDocs, there is no BasePolicyRuntime, so replace that with implement PolicyRuntime, {policy_name}Constants and that should work.

Let’s manually deploy using curl:

curl -X POST -u weblogic:{password} -k https://{mgmt_server}/apiplatform/administration/v1/policies -H "Content-Type:application/octet-stream" --data-binary @oracle.apiplatform.policies.{your_policy_name}.jar

If you’re successful, this is what you’ll get back

{"createdAt":"2018-04-06T14:25:23+0000","updatedBy":"weblogic","createdBy":"weblogic","name":"TESTPOLICY","description":"<Policy description>","type":"o:TESTPOLICY","version":"1.0","revision":1,"updatedAt":"2018-04-06T14:25:23+0000"}

Note that I have added a –k into my curl command to bypass SSL issues as I have not installed a proper cert in my demo environment. You should of course not do this in real-life.

You should see the policy successfully deployed:

The Ant script provides capabilities to Auto Increase the revision of the API and Auto Deploy to the Management Portal. Note that you have to increase the revision number of the policy each time you customize the policy and deploy it. The Management Server checks whether the policy version and revision stored in the database matches with the metadata in the policy that you are deploying. If that matches, the REST API returns an HTTP 200 code saying OK but no deployment happens. When you turn Auto Revision on the Ant script checks the Management Server for the latest version and increases it by 1.

Configure the build.properties file to turn those functions on:

Now running it again on the console, you should see the deployment occur.

Note that the scripts assume you have a http server connection or a valid https site. Because I am using a demo environment (you will likely be too) with an invalid SSL cert, we had to add code to ignore the SSL errors. Thanks so much Callan Howell-Pavia!

Grab my updated build.xml here. You should of course not do this in real-life.

Summary

And now we’re deployed and done! Attach the policy onto your API and run! Easy isn’t it? Now you can go wild adding policies such as performing transformations, extending to Reddis caches, logging to Splunk, send notifications of security breaches etc. Note that power comes with responsibility. Oracle’s position is not to put too much mid-tier transformation type activities in the Gateway as this typically sits in the DMZ. Read more about Oracle’s approach to layering your API architecture to protect your data by Robert Wunderlich, Product Manager. And thanks for dropping by our soap box 😉

Much thanks to John Graves and the A-Team for the knowledge imparted.