Retrieving Information from the REST API (The GET Request)

It is very simple to test out the functionality of the REST API using your browser. In the previous article I discussed how you both enable and connect to the REST API. Here I am are going to describe how you query the REST API to retrieve information about your TM1 model.

Before we get into the detail we need to understand a couple concepts about REST APIs in general. In REST terminology TM1 has a number of resources that can be retrieved, created, updated and deleted. From a TM1 perspective these are just objects: cubes, dimensions, processes, chores, cells, etc. 

Each resource has a unique URL that identifies what information is to be retrieved from TM1. For example if we want to retrieve information about a cube called General Ledger we would issue a GET request using the URL:

https://localhost:8881/api/v1/Cubes(‘General Ledger’)

A GET request is called a HTTP method and TM1 REST API supports 4 different HTTP methods:

• GET: Retrieves information about the resource specified in the URL.
• POST: Creates a resource in the TM1 server.
• PATCH: Updates an existing resource in the TM1 server.
• DELETE: Deletes an existing resource from the TM1 server.

The GET request is something that can be executed easily from your browser by typing the address into the Address Bar and pressing Enter. The other methods can only be executed in the browser with the assistance of an add-in like Postman (for Chrome), I will provide more information on how to do this in subsequent articles.

The first thing we are going to retrieve is a list of the cubes in our TM1 model. Go to your browser and type in the below URL and press ENTER:

NOTE: If your TM1 model has SSL enabled (the default) you will receive a warning about it being an untrusted or insecure connection. It is ok to ignore this message and proceed. 

You will be greeted by a pop-up dialog like the image below that will ask you for your TM1 credentials. This dialog uses what is called BASIC authentication and it is only supported when using traditional TM1 security, i.e. IntegratedSecurityMode 1 or 2. If you are using CAM security you should revert back to mode 1 or 2 on a dev/test environment so you can follow these examples.

Enter your regular TM1 credentials in this box and press Log In, i.e. if you are using the Planning Sample model for testing it would be: admin and apple. You will then be presented with a full list of every cube in your model including the rules. It will also look like a jumbled mess like the screenshot below:

This data is the JSON response from TM1, JSON is a text based format that is human readable, supported by nearly every programming language and is natively supported in web browsers. To help you understand what this information is I recommend installing a Chrome add-in called JSON Formatter, it will turn that previously ugly mess into this:

We can see from the screenshot above that TM1 is returning a list of cubes in the TM1 model. In this next example we are going to retrieve just a single object, in this case the General Ledger cube:

https://localhost:8881/api/v1/Cubes(‘General Ledger’)

Enter the above request into the browser address by appending (‘General Ledger’) and press Enter. Make sure you use single quotes, it is best to type these directly into the browser or use a text editor like Notepad or Notepad++. If you type the same single quotes into Microsoft Word or Outlook it will convert them to Smart Quotes which aren’t supported.

You will also note that any spaces are automatically converted by the browser to %20. This is called encoding the URL, for a full list how URLs should be encoded see this article.

The response you retrieve should look like this:

Before we move on to the next article Using $expand and $select with the TM1 REST API we should review the parts of the URLs above and describe what they mean. Example:

https://localhost:8881/api/v1/Cubes(‘General Ledger’)

Parts:

• https: This the scheme to be used, in this case https, which means use the HTTP protocol using secure sockets. If we were to disable SSL in the tm1s.cfg (UseSSL=F) we would use http instead.
• localhost: The location as a server name, IP address or domain name to access the REST API.
• 8881: The port number the TM1 REST API is running on, this has to the same number that you have used for the HttpPortNumber setting in the tm1s.cfg file.
• api/v1/: The version of the TM1 REST API that you are using, if for some reason breaking changes are made to the REST API the version will increment so no existing applications are broken.
• Cubes: The collection of resources that we are querying, this can also be Dimensions, Processes, Chores, etc. For a full list see the $metadata document: