TM1 REST API Project Structure and Pretty URLs

The great source of REST API best practices and development style offers free apigee collection of eBooks. 

URL Structure

Apigee folks suggest that URLs should exclusively consist of nouns declaring which object is requested and voluntary parameters for more precise specification. Examples include:

analyticshumanly.com/api/bears (get all data from Bears cube)

analyticshumanly.com/api/bears/Germany (get data from Bears cube about Germany)

However one TM1 server can include both Bears dimension and cube. In order to differentiate these object groups, I propose extending the URL with one of the possible category name: 

• dimension 
• subset 
• cube 
• view 

And again, some examples:

 analyticshumanly.com/api/cube/bears (get all data from Bears cube)

 analyticshumanly.com/api/dimension/bears (get all data from Bears dimension)

Methods handling

Now we have structure addressing every possible object with single specific URL. However, API needs to allow executing various operations (Select, Insert, Update, Delete) on every object. According Apigee, these methods should never be explicitly present in URL but rather provided in the HTTP method, such as:

GET analyticshumanly.com/api/cube/bears 

(get all data from Bears cube)

POST analyticshumanly.com/api/cube/bears/germany/2011/123 

(insert 123 units into Bears cube to Germany and 2011 intersection)

PUT  analyticshumanly.com/api/cube/bears/germany/2011/234

(update Bears at Germany and 2011 intersection to 234)

DELETE analyticshumanly.com/api/cube/bears

(delete cube Bears)

The code within the specific object such as bears.php in cube folder then needs to identify incoming method via $_SERVER[‘REQUEST_METHOD’] and implements own login for every operation. The code has been already presneted in the previous article and is repeated in the following snippet.

Project structure

Having in mind previous practices, I suggest using API project structure as shown at the following visualization. Yellow rectangles represent folders while blue are particular PHP files. Notice also position of the API library api.php.

TM1 API project structure

Pretty URLs

Secondly, notice that in all examples I excluded .php extension from final URLs. This can be obtained by URL rewriting in .HTACCESS file for Apache server. Rewrite rules heavily leverage regular expressions which can be little tricky at the beginning to crack, however powerful when master. Perfect beginners guide to regular expressions can be found at addedbytes.com.

In the following example, you can see how I rewrote api/cube/beras.php path to accept api/cube/bears URL with single line of code in .htaccess file placed in application’s root.