There’s a lot of excitement in the EPM world these days when it comes to REST APIs – and rightfully so. As a developer heavily invested in the EPM space I am excited about some of the possibilities these new APIs offer – and what they will offer in the future. But all of this great new REST API stuff can be quite daunting – how does it work, why should you care, where does it fit in with your overall architecture, and so on. And with ODTUG‘s Kscope18 just around the corner I thought it might be useful to write a primer – or a crash course of sorts – for the EPM professional on what all this REST API business is about. Also be sure to check out one of my presentations at Kscope this year as I will be discussing the OAC Essbase REST API, how to use it, what it does, and more.

REST APIs in a Nutshell

Many services in the Oracle EPM cloud space now have a REST API. PBCS was one of the first Oracle cloud services to get the ball rolling in this regard. Others have followed, such as FCCS, OAC, and more. But when someone says they have a REST API, what exactly does that mean?

For starters, it means that for the given service, there exists a way to programmatically interact with it. This is essentially the API (Application Programming Interface) aspect: as the consumer of the API, you might not and in fact often don’t care how it works, just that you have the capability to ask some black box to perform some action. For instance, maybe you want to run a calc script or a business rule in PBCS. As the consumer/user of the system, you don’t care how this happens or any of the gory details, you just want to know that you can tell it to do something and it’ll do it. It’s a black box to us because we don’t have any sense of the gory details: where things are on disk, how the script is written, which dimensions are dense and sparse, or anything.

The REST piece of things is a bit more nuanced. This means that the mechanism used to communicate with the service is HTTP. Yup, this is the exact same mechanism that your web browser uses to communicate with all of the websites that you browse. As it turns out, not only is HTTP a great protocol for humans to use to talk to computers around the world (a la the World Wide Web), it turns out that it’s amazingly effective at letting computers talk directly to other computers.

By way of contrast, for those of you that have been in the Essbase world for awhile, you might be aware of vaguely aware of this notion of a Java API that Essbase has that let’s you do just about anything you want with Essbase. Indeed, the Essbase Java API is quite capable and powerful, particularly if you already know Java. But what if you don’t know Java or your company has expertise in another programming language, such as C# or Python or something else? This is one of the key awesome things about REST APIs: they’re programming language agnostic.

So, whereas in the past you may have been dependent or beholden on some company to provide a Java JAR, or a DLL, or whatever, providing a REST API is effectively them saying, “Hey, use whatever language you want – you’re not dependent on us.” And you might not want to use Java either, which is also fine – most modern programming languages have very robust support for working with both HTTP and REST, be it Java, C/C++, C#, Python, JavaScript, Groovy, PHP, Swift, or something yet to come along.

What’s this JSON stuff?

JSON is generally used as the format of requests and responses to and from the REST service. JSON originally got popular by way of the JavaScript programming language (hence the name, JavaScript Object Notation). JSON lets you model both simple and complex data: arrays, lists, and objects, numbers, strings, and more. If you are familiar with XML, think of JSON as a less-verbose and lightweight way of defining data. In fact, anything that you can represent in XML you can represent with JSON. Here’s an example of the same data structured as both JSON and XML.

As another simple example, let’s say that we want to make a request to a service and that we’ll use JSON to specify the application, database/cube, and a data file to load:

{
  "application":"Sample",
  "cube":"Basic",
  "dataFile":"calcdat.txt"
}

In JSON terms, this is a pretty simple data structure. It’s an object with three keys: application, cube, and dataFile. The equivalent data structure in Java would be a Map<String, String>. Actually, because JSON supports objects of arbitrary complexity, the equivalent Java data structure would be Map<String, Object> (since the values can be strings or numbers or other objects).

I want to make a quick-aside on one of the reasons that JSON is a great format for exchanging data, particularly in APIs: it offers the developers and consumers of the web service a lot of flexibility when it comes to evolving and enhancing the API. With more traditional APIs, making changes would often result in backwards incompatibility and it would break things. It would often necessitate having to create and distribute a new library/module for your end users. But when using the JSON format, you can generally add in new keys/objects and older clients will still generally just work as they always did. For example, let’s say that the previous JSON example was the data format to specify loading a local data file on a cube, but now the developers (Oracle) want to enhance it with a new option that will automatically calculate the cube after loading the data file:

{
  "application":"Sample",
  "cube":"Basic",
  "dataFile":"calcdat.txt",
  "calcAfterLoad: "true"
}

You can see that there’s a new key called calcAfterLoad that takes a boolean (true/false) value. Again, old clients will continue to work without changes (the server will assume that the calcAfterLoad setting is false if unspecified), and clients that wish to upgrade can take advantage of the new functionality when they’re ready for it.

Because of the flexibility of the JSON data exchange format, you tend to see REST API versions evolve much more quickly than traditional APIs (as new things are added), while also [nicely enough] not actually breaking backwards compatibility. When fundamental changes need to be made, it’s pretty typical for the company/service offering the REST API to just create a new REST API side-by-side with the existing one (perhaps denoted with v1, v2, v3, etc.), and then tell developers that the old API is “deprecated”. To say something is deprecated is basically programmer-speak for “you can still use this for now but we reserve the right to get rid of it in the future, also, please don’t write any new code that uses these deprecated methods, for the aforementioned reasons”.

Okay, how about this cURL thing?

It’s quite common for services with a REST API to provide documentation on how to use the API in various forms. They’ll often include examples of request and response to various API methods, and they’ll also quite often show examples using a tool called cURL. cURL is a command-line client that makes HTTP requests to a given URL, almost exactly the same way that your web browser communicates with websites. cURL is shipped by default with Linux and macOS and is available as a download for Windows machines. It’s popular for many reasons. For starters, it’s free. It’s universally available, very capable, and very easy for developers/testers to copy/paste/edit examples and get started with an API.

Where does epmautomate fit in?

The EPM Automate tool is a command-line tool that can be used as part of automation. It ran load data, run business rules and more. It might not always be pretty but it gets the job done. The relationship of EPM Automate to the REST APIs is pretty direct: it uses them. So effectively, EPM Automate is a consumer of the REST APIs itself. This is also an example of what is called “dogfooding” in the software world: force yourself (the makers of EPM Automate) or one of your teams to use the functionality provided by another team (the PBCS or whichever service’s REST API). This is a good thing in the software world because it kind of forces you to actually test out the stuff you’re making in a real world way, instead of just pitching it over the fence to your end users and saying ¯\_(ツ)_/¯ in case something doesn’t work as expected.

So I can use EPM Automate and we’re all good, right?

Kind of. For many people, automation with EPM automation or even putting in calls to cURL in their automation will get the job done. And this will be good enough in many instances. I would add some caution to this approach, however. One, error control is notoriously complicated when using these low-level mechanisms. Things are fine when everything executes as it should, but when a single statement in a multi-line script fails, what happens? Intrepid developers will put in some guards to check the output or result code and alert the user as to an issue, and this will mitigate the risk of using these tools for many people – but not all. Wherever possible, I advocate for using a higher-level language (Java, Python, Groovy, whatever) for consuming the REST API, and then benefitting from the very advanced error handling and control flow that those languages give you. This is why I wrote the PBJ library – a high quality 100% Java, open-source and freely available Java library for working with the PBCS REST API.

The idea behind this library, and of designing a similar library in your chosen language is that it takes care of the details for you, and everyone benefits from getting to use such a library. For example, you’ll notice nothing to do with JSON, HTTP, REST, or anything in this simple example that calls a business rule:

PbcsClient client = new PbcsClientImpl(server, identityDomain, username, password);
PbcsApplication app = client.getApplication("Vision");
app.launchBusinessRule("AggAll");

Something that’s really great about having a solid, high-quality Java library as your foundation library is that you can use it transparently with other JVM languages, including Groovy, which is increasingly popular in the EPM world as an all purpose utility language. You can check out an example of using the PBJ library with a super simple Groovy script.

Wrapping Up

It’s an exciting time in the Oracle world with all of this new stuff with the cloud, REST APIs, and more. But it can also be quite daunting to keep up and more importantly, how it applies to you. I hope this primer helps you navigate the EPM seas. Please say hello next month at Kscope, and if you want to learn about Essbase’s new REST API, please come to my presentation where I’ll do my best to get you up and running!