Do you want to do more with TM1? Since TM1 10.2, IBM introduced the TM1 REST API which enables you now to do pretty much anything you want with your IBM TM1/Planning Analytics application.

In this post you will find everything you need to know to run your first TM1 REST API query and understand how to read the data.

The TM1 REST API for Dummies

The TM1 REST API is a way of accessing data and almost everything else in TM1. Rather than being a proprietary API like old TM1 interfaces, it is now based on web standards making it accessible to a wide range of developers.  

The TM1 REST API is fast and there are no external web servers or components you need to install. With the TM1 REST API you can do things that the traditional TM1 clients cannot do; such things as give me all cubes that share a specific dimension or execute MDX Queries to get cube data and much more…

Since its first introduction, IBM is continuously improving it on every new release. We recommend to use the TM1 REST API with TM1 10.2.2 FP5 as minimum.

A TM1 REST API query is a URL which looks like this:

• https://localhost:8882/api/v1/Dimensions

It has always the same components:

• protocol://servername:port/api/v1/resource

  • protocol is either http or https depending if SSL is setup.
  • servername server where TM1 instance is located.
  • port: the port is the httpPortNumber parameter value in the tm1s.cfg.
  • resource: The resource you want to retrieve, e.g. Dimensions to retrieve all dimensions or Cubes to retrive all cubes.

Let’s have a look at an easy example. To get the list for all dimensions you can use the following URL in your browser:

• https://localhost:8882/api/v1/Dimensions

Before running this query you should make sure that REST API is enabled on your TM1 instance. The data you will get will be returned in JSON (JavaScript Object Notation) format.

As you can see above, in the browser the JSON format is not easily readable but do not worry there are lots of tools online which can help you to format it. For example, if you copy the content from the browser and paste it into the JSON viewer, in the viewer tab you will see the data structure:

Instead of doing these steps manually (running the query and then viewing the data into a JSON viewer), you can use a tool which will do this for you and it is called Postman.

Postman makes the TM1 REST API easy!

Postman is a modern HTTP Client with a fancy interface. It makes interaction with TM1 through the TM1 REST API easier compared to doing it through Chrome, CURL or a programming language.

Postman has a free app that you can download here: getpostman.com. Once downloaded, just run the exe file. The installation should take less than a minute.

Postman will start and it will ask you to sign-in. You can choose to create an account or to click on “Take me straight to the app”. The advantage of signing up is that Postman will save your work in its cloud and you will be able to retrieve your work on another laptop after you have signed in.

• https://localhost:8882/api/v1/Dimensions

In this example the TM1 instance uses the basic TM1 Security with user admin and no password. In the authorization tab, we select Basic Auth and then we input username and password. Click the Send button to run the query:

Ater clicking the Send button if you get the error as above you might have to turn off SSL. To do that, go to File then Settings and un-check Postman’ SSL certification verification:

Then click the Send button. Once setup, you should be able to see the list of dimensions in the Body section:

If you want to get the list of cubes instead of the list of dimensions you can replace Dimensions with Cubes:

• https://localhost:8882/api/v1/Cubes

To run a TM1 REST API query on a TM1 instance using CAM Security you will have to change the Authorization to No Auth.

First what you need to do is to encrypt your CAM user password. To do that you can use sites such as the base64encode.org website. Click on the Encode tab and type user:password:AD and then click Encode, it is going to encode the string:

If you are not sure about the AD, you can log in to Architect and check the user. In this example, after logging in to architect, the user is ADuser.

In Postman, you will then need to set the Authorization type to No Auth:

In the headers tab, add a new key with Authorization and as value CAMNamespace + the Base64 format encoded authentication

That is it! You are now ready to dig into the TM1 REST API. To help you to start with, we have gathered all the most important TM1 REST API queries into a Postman collection, you can download it here:

If you interested of building web-based TM1 planning and reporting application, you should have a look at Canvas which is a web development framework.

If you want to integrate systems with your TM1/Planning Analytics application, you should have a look at TM1py which is a Python package that wraps the TM1 REST API in a simple-to-use library.

• A journey through the TM1 REST API
• More TM1 REST API examples
• The differences between IBM Planning Analytics Workspace and Canvas