You can find a lot of content on how to start using TM1’s REST API, for example here, here or here. However, to the best of our knowledge, until now there hasen’t been any guidance to be found anywhere on what changes you may need to make to an existing model to make it “REST API ready” or for that matter principles to keep in mind when creating a new TM1 model which will be consumed via REST API interfaces. We want to address this gap and give some solid practical advice for TM1 developers and administrators who might be wondering what to do in such situations.
For your application to communicate with your TM1 Server via REST API you need to make sure a unique port across all services running on the host server is allocated. You do this by setting the HTTPPortNumber parameter in the tm1s.cfg file. If this parameter is absent from the configuration file then the default http(s) port value is 5001. The HTTPPortNumber parameter works in conjunction with the UseSSL parameter. If UseSSL=true (the default value) then the TM1server will accept only secure https connections.
Key points to remember:
To enable READ / (WRITE) access to a cube a group requires:
And as far as the old APIs were concenred that was pretty much it. With the following exceptions for special use cases:
In addition to setting READ / WRITE cube securuty access and READ access to each dimension in the cube, for access via the the TM1 REST API to function properly, groups now also require:
Note: that strictly speaking explicit access to the attribute cube and attribute dimension isn’t absolutely necessary. A Rest based UI should still work without this, but things will work better and faster with this access. (This is due to a Rest API & OData quirk on requesting a single attribute value versus all attribute values for a given dimension.) And don’t forget that for many features MDX will be used, and quite often in advanced MDX explicit reference is made to attribute cubes. Without this access there will almost guaranteed be features that won’t work properly.
Also depending on the version of the TM1 server (and Rest API) and/or the version of PA Workspace you may also need:
The first several versions of the TM1 REST API supported only MDX Select queries and did not support MDX Set Expressions. Therefore the “native” way to query a dimension via the REST API is to query the dimension’s }ElementAttributes cube. In the initial versions of PAW the subset editor would actually fail if a dimension contained no attributes (and hence the }ElementAttributes cube was absent). Obviously, this functionality gap has since been closed but due to code legacy and backwards compatibility the default query method is always to use the }ElementAttributes cube if it exists. In any case without READ access to the respective attribute cube users will be unable to see any attribute values.
This leads to some recommended best practices when designing models which will be consumed via a TM1 REST API interface:
Many people don’t realize but the Caption attribute doesn’t have to be an alias. In fact it is better practice to make Caption a string as this will give you more flexibility and allow the application to be more user friendly. Even if values are not unique, Caption attributes work much the same as aliases for display purposes in all native REST API interfaces; if no caption is set then the principal name will be displayed, otherwise the caption.
This blog article is a condensed version of of an Apliqo UX Technote. The full technote also contains