Feb 4, 2018

The TM1 REST API Collection for Postman

The TM1 REST API is a way of accessing data and almost everything else in TM1. With the TM1 REST API you do things that normal TM1 clients cannot do such as:

  • Get all cubes that share a particular dimension
  • Get all processes that have an ODBC Datasource
  • Get the last 10 message log entries that were referring to a certain process

Tackling the TM1 REST API by yourself can be challenging. To help you to start with, we have gathered all the main TM1 REST API queries in a ready to use Postman Collection. What you just need to do is to download Postman and then follow these steps to set up the TM1 REST API Collection for Postman.

If you are not familiar with Postman, you should read the following article which will explain how to install Postman and how to run your first TM1 REST API Query:

Download the TM1 REST API Collection

A Postman collection lets you group individual requests together. To download the TM1 REST API Collection just click on the following button:

Once downloaded you should see two files:

  • Canvas Sample.postman_environment.json: Contains information about the TM1 instance you want to query.
  • The TM1 REST API.postman_collection.json: Contains all TM1 REST API queries.

Import the TM1 REST API Collection

To import a Collection in Postman, just click the import button in the top left corner and then pick the The TM1 REST API.postman_collection.json file:

Once imported, you can click on the Collections tab where you should be able to see the TM1 REST API folders

Inside these folder, the queries are split into 5 sub-folders:

  • Cubes: Get all cubes, Execute a view…
  • Dimensions: Get all dimensions, create/delete dimensions or elements…
  • Processes: Execute or Update processes…
  • Chores: Execute or Update chores…
  • Administration: Get configureation, sessions, threads…

If you click on the first query Cubes Get, you will see that the URL uses parameters such as {{protocol}} or {{serverName}}:

Instead of hard coding the protocol, server name and httpPortNumber we use variables defined in a Postman Environment. If the variables are red, it means that they are missing in the Environment variables list. In this example there is no Environment setup, on the top right you should see “No Environment“:

Create a new Postman Environment

An environment in Postman enables you to save variables that you can then use in the URL. You can choose to create the environment manually or just upload the Canvas Sample.postman_environment file that you can find in the same folder you just downloaded. To import this file, go to Manage Environment:

Click the Import button and then select Canvas Sample.postman_environment.json file:

Once imported you should be able to see the new environment Canvas Sample:

Click on the environment to see all the variables:

if you select now your environment from the dropdown list on the top right, the variables in the URL should turn orange, orange means that Postman has found the variables in the environment selected (if one variable is missing, it is going to be red):

Manage authentication

In the Authorization tab you can notice that it is set to Inherit auth from parent. Instead of defining the credentials for each query, the credentials are stored in one location, the parent folder. To update the credentials, click the edit button of the collection:

Set the proper credential in the Authorization tab. In this example we are using basic TM1 Authentication (mode 1).

More information about how to set up Authorization with CAM Security can be found in this article:

You should now be able to run the query by clicking on the Send button. If you get the following error, it might be due to the SSL:

To disable SSL certificate version, go to File > Settings and turn off the SSL certificate verification:

If you click send, you should now be able to see the list of cubes:

If it still does not work, you should check first your environment variables and then check if the TM1 REST API is enabled for your TM1 instance.

Explore the TM1 REST API Collection

You are all set! You can now run all queries. Do not forget to update the Environment variables to match the information of your TM1 instance and your TM1 objects you want to query such as cube, process and chore.

What to do next?

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.


Related content

Loading related content