TM1/PA REST API Part 4: Understanding Server Response

This blog post is continuation of making API call and understanding the server response. I will share some tricks to cutdown the payload received. In addition, I will demonstrate few request URLs that you can work with. This post is an intermediate level and therefore assumes you are familiar with making an API call using Postman.

In my last post, we executed an API call that lists all the cubes from an IBM Sample server SData (or any TM1 instance where the request URL was sent to). To verify if the API call was successful, in the Postman Body, you should see a 200 OK message.

EDM (ENTITY DATA MODEL) of cube
The request URL that was sent as part of the API call, requested all the Cubes. The EDM structure of the Cube entity is shown below. The EDM can be found in the REST API section of the guide. Cube entity container has Properties as well as Navigation Properties. When a request URL asks for Cube entity, unless specified, it will return all of the Properties in the record set.

---

EDM and Server Response
For a request URL that lists all the cubes from the server, the Postman Body will show you the server response. The reason, the response from server looks like this, is because of the EDM structure of the entity you queried. In the below screenshot you can see the EDM structure of Cube, mapped to the response received from the server


On a similar lines, if I had queried for dimensions using a request URL of https://server-name-or-ip:port/api/v1/Dimensions, then the response displayed in Postman along with the mapping of the EDM structure of dimension will look like below:

The above examples illustrate return of all the properties, which usually does NOT bode well for performance. A good practice is to limit the payload by using $select query option to limit the properties we are interested in. More on this below.

---

Select Certain Properties
In a SQL query you can limit the columns you are interested from a given table(s). In a similar manner, you can use the query options in the request URL, to select the properties of an entity that you are interested in. We’ve seen (from above screenshot) the entity container of Cube consists of these Properties: Name, Rules, DrillthroughRules, LastSchemaUpdate, LastDataUpdate and Attributes. Entity container of Cube also have Navigation properties, we will deal with that later.

As an example, a request URL to select only the Name and its Rules from Cube entity will look like this:
https://server-name-or-ip:port/api/v1/Cubes?$select=Name,Rules
Response for above request URL will look like below. Notice the @odata.context – it tells us the properties requested in the URL. In addition, for each of the cubes we are also seeing a line in the response highlighted in yellow that begins with @odata.etag

Let’s add a new key in the Headers tab of Postman. The key name is Accept with a value of */*; odata.metadata=none

This header key will remove the @odata.etag lines from the payload; thus cutting down the volume of payload and improving the response times of your API calls.

---

Viewing Navigation Properties
A Cube entity has multiple Navigation Properties (you can check out the screenshot at the top). Let’s say you are interested in Dimensions. Querying the navigation property of dimension for a record in the Cube entity, will list all all of its dimensions. I will illustrate usage of this with few examples:

1) A request URL to view the dimensions of PNLCube foundin SData TM1 instance will be like this:
https://server-name-or-ip:port/api/v1/Cubes('PNLCube')/Dimensions

2) If we are just interested in the Name of the dimension and not other properties, you can use $select query option to achieve this. The request URL will now look like this:
https://server-name-or-ip:port/api/v1/Cubes('PNLCube')/Dimensions?$select=Name

3) Continuing further, if you are interested in the number of dimensions of PNLCube, you request URL will be:
https://server-name-or-ip:port/api/v1/Cubes('PNLCube')/Dimensions/$count

In the above three examples, we are working with only one cube i.e. PNLCube. What if you want to get same answer for all of your cubes? Fortunately OData provides us with $expand option to work with. For the three examples of above, check out the request URLs to work with all of the cubes.

1a) Request URL to view dimensions of all the cube names on the TM1 instance
https://server-name-or-ip:port/api/v1/Cubes?$select=Name&$expand=Dimensions

2a) Request URL to view just the dimension names along with all the cube names on the TM1 instance
https://server-name-or-ip:port/api/v1/Cubes?$select=Name&$expand=Dimensions($select=Name)

3a) Get count of all the cubes on the TM1 instance
https://server-name-or-ip:port/api/v1/Cubes?$select=Name&$expand=Dimensions/$count

---

Points to Note:
* Entity types are case sensitive.
Works: https://server-name-or-ip:port/api/v1/Cubes
Does NOT work: https://server-name-or-ip:port/api/v1/cubes
* Properties of an entity are case sensitive.
Works: https://server-name-or-ip:port/api/v1/Cubes?$select=Name,Rules
Does NOT work, https://server-name-or-ip:port/api/v1/Cubes?$select=name,Rules (N in the Name property is written in small case)
* Record names in an entity are NOT case sensitive. This is the case for the REST API implementation of TM1. Both request URLs listed below yield the same result
https://server-name-or-ip:port/api/v1/Cubes('PNLCube')/Dimensions?$select=Name
https://server-name-or-ip:port/api/v1/Cubes('pnlCube')/Dimensions?$select=Name

---

▬▬▬▬▬▬▬▬▬▬▬▬▬▬ஜ۩۞۩ஜ▬▬▬▬▬▬▬▬▬▬▬▬▬▬

Related posts on TM1/PA REST API

Sl No	Title with brief description
1	TM1/PA REST API Part 1: Introduction – Getting it Right There are few things to understand before getting into the weeds of working with the TM1 REST API. This post is an absolute introduction to shed some light on the pre-requisites, for interacting with TM1 REST API.
2	TM1/PA REST API Part 2: Introduction – Get started with Postman This post introduces you to an API client – Postman, to help you get started and to dip your toes in the water, to test out the TM1 REST API functionality.
3	TM1/PA REST API Part 3: Execution – Making an API Call This post demonstrates a detailed example to make a TM1 REST API Call – specifically GET method of an HTTP request. We will see how to form the URL, put proper settings in Postman and ensure we get the result we want from TM1/PA server.
4	TM1/PA REST API Part 4: Understanding Server Response In this post, we will continue our journey in understanding the TM1 Rest API. We will understand server response, map it with the EDM structure. I will share some tricks to cutdown the payload received from the server.
5	TM1/PA REST API Part 5: Trivia on Base64 Encoding This post is a trivia on Base64 encoding. We will see the significance of number 64, why there are sometimes one or two equal to signs.