Note: this article was originally written for an ODTUG publication, but it never wound up getting published. So I thought I would just post it here instead.

Oracle’s Planning and Budgeting Cloud Service – PBCS – is the first Hyperion product to get the full cloud treatment. In addition to Planning’s move to the cloud, it has picked up a couple of new tricks. One of these new features is a REST API. This article will give a quick background on REST APIs, some integration opportunities now available to PBCS users, and information on how the PBCS REST API can be easily used from Java.

For those that aren’t familiar, a REST API typically means a few things to developers. First of all, an API is an application programming interface. From a developer standpoint, an API gives us the ability to write programs that interact with another system in a specific way. In the case of PBCS, the API provides access to functionality such as refreshing a cube, launching a business rule, uploading files, getting member information, and more.

APIs have been around for decades. This whole REST business is a little newer. REST APIs, or “RESTful web services” are APIs that are accessed over the web using the same technology that a web browser uses to communicate with websites on the internet. Additionally, REST APIs are often designed in a specific way that models objects and actions in an organized hierarchy. Lastly, the typical request and response is formatted as JSON object. JSON is a popular data format that originated in the JavaScript programming language. You can think of it as a lightweight, easy to read text format that can represent arbitrarily complex information.

One of the great things about REST APIs is that they open up a lot of integration opportunities that might not have existed before. In the past, when it came to interacting with a system such as PBCS, developers were often completely reliant on the third-party such as Oracle to develop libraries in a specific programming language such as C++ or Java. But since a REST API just uses common protocols and data formats, almost any modern programming language can interact with it. Now instead of maybe just a couple of languages being supported, it’s relatively easy to get up and running, be it C++, Java, JavaScript, Python, PHP, Groovy, PowerShell or something else.

The PBCS automation tool itself – epmautomate – uses the PBCS REST API to run rules, refresh cubes, and more. This brings me to my main point. For many organizations, the epmautomate tool is going to be the quickest and simplest way to script automation. But many organizations are going to need to interact with PBCS in other ways.

There are numerous integration use-cases for the PBCS that will involve the REST API. For example, an organization may want to write automation in a higher-level programming language than the command line. Or they may need to kick off a job on PBCS or fetch live member information programmatically. These things are both easily achievable.

For integration scenarios that do happen to be in the Java programming language, there is even already a bespoke Java library that works with the PBCS REST API and makes automation possible with just a few lines of code. This library is called PBJ (PBCS Java Client) and is an open source library that is freely available. It can be found at http://github.com/jasonwjones/pbj-pbcs-client along with documentation and examples of how to use the library.

Lastly, for those that want to interact with the PBCS REST API using another language, the PBJ library can be used as a reference and complement to the Oracle documentation on how certain functions work. I can’t overstate this last point quite enough: all APIs and libraries (especially new ones!) have their quirks, so when someone has already figured it out, use their experience when you can in order to speed up your own development.