I am no stranger when it comes to Web Services and in particular REST APIs which I have been covering for a number of years now, I am a strong believer that they play an important part in integration and automation. With the rise of the cloud, REST APIs are integral to process automation between different cloud services.
In the past I have covered on-premise Essbase Web Services which is based on the SOAP protocol, the preferred method these days is REST and prevalent in most cloud services. I definitely enjoy working with REST over SOAP, mainly for its simplicity and ease of use.
The 11.1.2.4 Essbase patch releases have contained the following in the readme:
"JAPI SOAP web services will be removed in a future release and they will be replaced with REST APIs."
Unfortunately for on-premise Essbase this has not yet happened and it is unclear when it will happen.
It is a different case for the Essbase side of Oracle Analytics Cloud (OAC) where a REST API is available. Though unless I am missing something it does not seem to be well documented yet but I am sure that will change over time.
I have to assume that one day the REST API will also be pushed down from cloud to on-premise, but for now I will be covering what I have found available in the Essbase cloud service. In this first part I am going to go through a really quick introduction in getting started with the REST API.
Just in case you are not aware, the OAC – Essbase Command-Line Interface (EssCLI) is built on top of the REST API so you may have already inadvertently been using the API.
Getting started with the REST API is simple, all you need is a REST client. There are lots of REST clients available as add-ons for most browsers, alternatively standalone apps like Postman or Insomnia.
If you want to take using REST a stage further, for say automation, then most scripting languages provide the functionality to achieve this.
I am going to stick with what I have been doing for the last few years, using the Boomerang app for Chrome and for scripting PowerShell, mainly for demo purposes and ease of use. The concept will be the same whichever client or scripting language you choose to use.
I won’t go into detail on what I have already covered in the past but here is a description of REST from my first post on the planning REST API:
REST describes any simple interface that transmits data over a standardized interface (such as HTTP) without an additional messaging layer, such as SOAP.
REST provides a set of design rules for creating stateless services that are viewed as resources, or sources of specific information, and can be identified by their unique URIs.
RESTful web services are services that are built according to REST principles and, as such, are designed to work well on the Web. Typically, RESTful web services are built on the HTTP protocol and implement operations that map to the common HTTP methods, such as GET, POST, PUT, and DELETE to retrieve, create, update, and delete resources, respectively.
Examples of each method in terms of Essbase could be:
GET – Retrieve a list of applications, databases or logged in users.
POST – Execute a calculation, MDX or MaxL script.
PUT – Update a calc script, substitution variable or filter.
DELETE – Delete an application, script, variable or filter.
The URL structure to access Essbase REST resources would follow the lines of:
https://<oac_essbase_instance>/rest/{api_version}/{path}
Currently the api_version is v1.
So let’s start out with one of the most basic resources to return the version information, this is the same as selecting ‘about’ in the web UI.
The EssCli has a command to return the version.
Using a REST API client, you would just need to enter base REST API URL plus “about”, for example:
Before you run the request, you will also need to enter your credentials.
This will add a basic authorization header to the request with the username and password base64 encoded.
Now you are ready to execute the request and receive a response back in JSON format.
To convert this into a scripting equivalent does not take much effort.
Basically, the user credentials are encoded into base64 and added to the request header, this is automatically done for you when using a REST client.
The URL for the about REST resource is defined, a GET request is made to the URL and the response stored, this is then outputted.
To return session information about the user making the REST request, then all that is required is “session” suffixed to the base URL.
In terms of scripting, the existing script only requires the URL updating to include “session”
To retrieve a list of Essbase provisioned users then the “users” resource can be accessed.
This will return a list of user information in text format, there is an equivalent resource for returning group information, no surprise that this is accessed with “/groups”.
To retrieve information on which users are logged into the Essbase instance then the “sessions” resource can be requested.
The same script could be updated to return a list of logged in users and the time they have been logged in.
I am going to leave it there for this post and in the next part I will get into some of the more interesting REST API resources available.
In the past I have covered on-premise Essbase Web Services which is based on the SOAP protocol, the preferred method these days is REST and prevalent in most cloud services. I definitely enjoy working with REST over SOAP, mainly for its simplicity and ease of use.
The 11.1.2.4 Essbase patch releases have contained the following in the readme:
"JAPI SOAP web services will be removed in a future release and they will be replaced with REST APIs."
Unfortunately for on-premise Essbase this has not yet happened and it is unclear when it will happen.
It is a different case for the Essbase side of Oracle Analytics Cloud (OAC) where a REST API is available. Though unless I am missing something it does not seem to be well documented yet but I am sure that will change over time.
I have to assume that one day the REST API will also be pushed down from cloud to on-premise, but for now I will be covering what I have found available in the Essbase cloud service. In this first part I am going to go through a really quick introduction in getting started with the REST API.
Just in case you are not aware, the OAC – Essbase Command-Line Interface (EssCLI) is built on top of the REST API so you may have already inadvertently been using the API.
Getting started with the REST API is simple, all you need is a REST client. There are lots of REST clients available as add-ons for most browsers, alternatively standalone apps like Postman or Insomnia.
If you want to take using REST a stage further, for say automation, then most scripting languages provide the functionality to achieve this.
I am going to stick with what I have been doing for the last few years, using the Boomerang app for Chrome and for scripting PowerShell, mainly for demo purposes and ease of use. The concept will be the same whichever client or scripting language you choose to use.
I won’t go into detail on what I have already covered in the past but here is a description of REST from my first post on the planning REST API:
REST describes any simple interface that transmits data over a standardized interface (such as HTTP) without an additional messaging layer, such as SOAP.
REST provides a set of design rules for creating stateless services that are viewed as resources, or sources of specific information, and can be identified by their unique URIs.
RESTful web services are services that are built according to REST principles and, as such, are designed to work well on the Web. Typically, RESTful web services are built on the HTTP protocol and implement operations that map to the common HTTP methods, such as GET, POST, PUT, and DELETE to retrieve, create, update, and delete resources, respectively.
Examples of each method in terms of Essbase could be:
GET – Retrieve a list of applications, databases or logged in users.
POST – Execute a calculation, MDX or MaxL script.
PUT – Update a calc script, substitution variable or filter.
DELETE – Delete an application, script, variable or filter.
The URL structure to access Essbase REST resources would follow the lines of:
https://<oac_essbase_instance>/rest/{api_version}/{path}
Currently the api_version is v1.
So let’s start out with one of the most basic resources to return the version information, this is the same as selecting ‘about’ in the web UI.
The EssCli has a command to return the version.
Using a REST API client, you would just need to enter base REST API URL plus “about”, for example:
Before you run the request, you will also need to enter your credentials.
This will add a basic authorization header to the request with the username and password base64 encoded.
Now you are ready to execute the request and receive a response back in JSON format.
To convert this into a scripting equivalent does not take much effort.
Basically, the user credentials are encoded into base64 and added to the request header, this is automatically done for you when using a REST client.
The URL for the about REST resource is defined, a GET request is made to the URL and the response stored, this is then outputted.
To return session information about the user making the REST request, then all that is required is “session” suffixed to the base URL.
In terms of scripting, the existing script only requires the URL updating to include “session”
To retrieve a list of Essbase provisioned users then the “users” resource can be accessed.
This will return a list of user information in text format, there is an equivalent resource for returning group information, no surprise that this is accessed with “/groups”.
To retrieve information on which users are logged into the Essbase instance then the “sessions” resource can be requested.
The same script could be updated to return a list of logged in users and the time they have been logged in.
I am going to leave it there for this post and in the next part I will get into some of the more interesting REST API resources available.
