Essbase REST API - Part 2

In the last part I introduced the Essbase REST API which is currently only available in OAC, though you never know it might make it down to on-premise one day.

It seems like a big chunk of the functionality in the Essbase web UI is built around REST which means you should be able to achieve a lot with it.

In this part, I am going to cover REST resources that could form part of Essbase application and database monitoring such as retrieving available applications/database and properties, starting, stopping and deleting.

As explained in the last post the URL structure to access the REST API will be:

https://<oac_essbase_instance>/rest/v1/{path}

Once again, I am going to use a combination of a REST client and example scripting. I am not getting into a debate about which is the best client or scripting language as that usually boils down to personal choice, the idea is to provide information on some of the Essbase REST API resources that are out there.

So let us start out with returning a list of applications.

The format of the URL is:

https://<oac_essbase_instance>/rest/v1/applications

An example of the URL would be something like:

If we put this in to a REST client and make a GET request the following response will be received in JSON format.

A list of available applications will be returned and some properties, such as whether the application is started, and the type. You will notice that the creation and modified time are in Unix time which basically means the number of seconds since 1st Jan 1970.

Included in the response are four http links that provide the ability to start, stop and delete the application, as well as return a list of databases, I will get on to these shortly.

Any of the responses that return links can be suppressed with a query parameter and value of “links=none”

For example:

The response will be returned without links.

In terms of scripting, I am going to start out with the same script I used in the last post, the only difference this time is I am including applications in the path and the parameter to suppress links.

This means with a simple script a list of applications can be returned and associated properties.

If I wanted to return the applications that are currently started:

I could take this a step further and show which applications are started and when they were started, in this example I current the Unix time into an understandable timestamp.

It is just as simple to return only BSO or ASO applications.

To display the total number of applications there is a property named “totalResults” that is available.

This matches to the value shown in the UI.

To return settings for the application then settings can be included in the path, if you include a query parameter and value of “expand=all”.

GET - https://<oac_essbase_instance>/rest/v1/applications/{appName}/settings?expand=all

The option to suppress the links could have been included, the following settings and values are returned in the response.

Going back to the links that were shown earlier, there is the ability to start and stop an application.

In the UI we can see the sample applications are stopped.

With a REST client I can simply add the URL to start the Sample application, a PUT method is required.

PUT - https://<oac_essbase_instance>/rest/v1/applications/{appName}?action=start

If the operation is successful, a http status code of 200 will be returned with no JSON.

To stop the application, all that is required is a quick change to the URL to include the action parameter with a value of stop.

PUT - https://<oac_essbase_instance>/rest/v1/applications/{appName}?action=stop

If a http status code of 200 is returned the application should be stopped.

If you try and stop an application that has been stopped, a status code of 400 will be returned with an error message in JSON format.

It is similar if you try and start an application that is already started.

The message is the same if you try the same operations in the web UI.

Moving on to the delete link which is included in the response when listing applications.

In this example I am going to delete an application named “Sample-MTL”.

This time a delete method is required with the application name included in the URL.

DELETE - https://<oac_essbase_instance>/rest/v1/applications/{appName}

If the operation is successful, a http status code of 204 with no JSON is returned.

In the UI, the application has been deleted and now there are 5 applications in total.

The remaining link that is returned provides the ability to list the databases that are part of the application.

In this example, the Sample has two databases.

The URL includes the application and databases in the path, to return a list of databases and properties a GET method is required.

GET - https://<oac_essbase_instance>/rest/v1/applications/{appName}/databases

The list of properties that are returned are the same as with applications, there is only one link that allows you to return a single database, but the properties that are returned are exactly the same.

In terms of scripting, the previous script could be updated to provide a list of all applications and databases.

First, all the applications are returned and then a loop cycles through each of them, for each application the databases are returned, these are cycled through and the name of the application and database are displayed.

Any of the properties could have been included so it could have displayed all the applications and databases that were started and when they are were started.

To get a list of database settings then the URL requires databases and the database name like:

GET - https://<oac_essbase_instance>/rest/v1/applications/{appName}/databases/{dbName}/settings

Including the expand parameter will return all the available settings.

If settings are not enabled they will not be returned, calculation has not returned any properties, if you look in the Essbase UI there are the following settings:

If I update the aggregate missing values setting.

This time the setting is included in the response.

To update the setting, it should be possible using a PATCH method, unfortunately this is not working for me in the current release.

In theory it should be something along the lines of:

PATCH - https://<oac_essbase_instance>/rest/v1/applications/{appName}/databases/{dbName}/settings

To obtain the database statistics the following URL can be used with a GET request:

GET - https://<oac_essbase_instance>/rest/v1/applications/{appName}/databases/{dbName}/statistics

This will provide a response of:

No information is currently being returned for runtime but this is similar to the UI, so maybe just related to the version.

Any of this information can be returned with a script, in the following example the statistics and settings for the sample basic database are returned, the start time of the database is converted from Unix time using a function.

The properties and values are only outputted to the console window as an example, these could easily be turned into a report or sent out by email, alternatively actions could have been taken depending on the returned values.

With all these different resources available through the REST API, it provides an excellent alternative for Essbase monitoring.

In the next part I am going to move on to managing substitution variables, filters and calculation scripts.