What’s new in Tableau Server 9 Rest API – The long story
March 26, 2015
, , ,

This is one those “why do we love tableau 9” posts which are spreading on the internet with one exception. To understand the new Rest API’s value first you should see its history, evolving from the nothing thru the uselessness until its current, lovely form.

The era of nothing

Prior to 8.2 there was no official way to programmatically invoke server procedures. The only supported interaction with the server outside of Desktop and Server was the tabcmd tool. As Tabcmd written entirely in jruby, therefore it was a little bit slow and non-interactive. After my post on how to make it run on linux people started to make their contribution like Sam Caldwell who made a full automated solution to move out tabcmd from the java space. However, not only the speed was the concern. Tabcmd still lacks basic features like getting members of a group or list workbooks in a project. It is fine if you want to upload or download something, add a branch of users to a site but for real automations this is still not enough.

But if there is a need there will be a workaround as well.  Since Tableau Server’s web application, the workgroup server (c’mon, why is it called as workgroup?) was running on rails at that time, the controller actions were accessible thru non-htmlish format. People realized that they can get list of users or members of a group thru /users.xml url. They still needed to parse the results, but at least with these “hidden” URLs they were able to do things from batches which were not possible with official tools. Two years ago one of my solutions was to add the missing functionalities to tabcmd like sending workbooks directly on email in PDF format or check users against audit rules. It was fine, however, not really manageable so I came out with an another idea.

The “undocumented” Rest API

By reverse engineering tabcmd’s and Desktop’s communication with the server it turned out that removing tabcmd from the equation and invoke server functions directly would be much easier. I wrote an blog post with example code two years ago in ruby which was followed by numerous contribution like how to do the same in C# or Java. Later on Zen Master Craig Bloodworth released his Alteryx Tools for Tableau based on this “undocumented” API. We built our change, release and version control tool for Tableau on this API as well.

Of course we had some issues. Sometimes Tableau software was kind enough to fix issues on these “undocumented” entry points. For instance hitting the /users.xml path which returns user information for groups caused server crashes on systems where the number of users exceeds 10.000. This was reported, soon tableau made a patch which solved issue.

My company also made dozen of solutions for our customers based on this API, so when I realized that there will be no rails web app in the future, I started to be scared. I do not want to tease too much, but Tableau still maintains this rails style web service API in Tableau 9.0beta9, even if the complete web application framework changed including the programming language.

Calling Undocumented API on Tableau 9

Calling Undocumented API on Tableau 9

It seems this undocumented API will survive, but as it is not supported we might move it to the official Server Rest API. Well, maybe yes, but with Server 8.2 Rest API the answer is not obvious.

Official Server Rest API in 8.2

To understand the value of Tableau Server 9 Rest API first you must understand the uselessness of Server API 8.2. The API itself, the documentation and functionality were just unprofessional.

The following Table compares the functionality of the two versions. As you see, from 8.2 almost everything is missing.

Category Function 8.2 9.0
Authentication Sign In X X
Sign Out X X
Sites Create Site X X
Query Site X X
Query Sites X X
Update Site X X
Delete Site X X
Projects Create Project X X
Query Projects X
Update Project X X
Delete Project X X
Workbooks Publish Workbook X
Add Tags to Workbook X X
Query Views for Workbook X X
Query View with a Preview Image X X
Query Workbook X X
Query Workbook Connections X
Query Workbook Preview Image X X
Query Workbooks for User X X
Download Workbook X
Update Workbook X
Update Workbook Connection X
Delete Workbook X
Delete Tag from Workbook X X
Data sources Publish Datasource X
Query Datasource X X
Query Datasources X X
Download Datasource X
Update Datasource X
Update Datasource Connection X
Delete Datasource X
Users and Groups Create Group X
Add User to Group X
Add User to Site X X
Get Users in Group X
Get Users on Site X X
Query Groups X
Query User On Site X
Update Group X
Update User X
Remove User from Group X
Remove User from Site X X
Permissions Add Datasource Permissions X
Add Project Permissions X
Add Workbook Permissions X
Query Datasource Permissions X
Query Project Permissions X
Query Workbook Permissions X
Delete Datasource Permissions X
Delete Project Permission X
Delete Workbook Permissions X
Jobs Query Job X
Favorites Add View to Favorites X
Add Workbook to Favorites X X
Delete View from Favorites X
Delete Workbook from Favorites X X
Publishing Initiate File Upload X
Append to File Upload X
Publish Datasource X
Publish Workbook X


In fact, with 8.2 you cannot cover the most basic tasks like:

  • Upload a workbook
  • Move objects from one Tableau Server to an another
  • Synchronize objects with a version control system
  • Synchronize users for all groups with a csv file
  • Trigger a schedule
  • Refresh an extract on the server with flat TDE file

You can do any of them with the undocumented REST API, but none of them with the official one. It was quite disappointing.

From documentation perspective it was not the best too. Let’s check the API reference, we do not see update user method:

8.2 API's user related Functions

However, in the 9.0 docs:

9.0 user1





9.0 user2



This method was required to assign a password to a user after its creation. Without documenting this function no one was able to create user with password authentication. It was there all the time but nobody noticed or documented it. You can guess how many people used it.

Last but not least the example program in python. It start with the following class initializer:

Takes the site as parameter but do not use it. Later:

What is going on here? First of all we defined the site parameter which always gets empty string. And since the API is not robust enough even if the site name would passed to signin, it would not return the corresponding site id which is required for all subsequent calls. The guy who wrote the example solved this by adding a hardcoded site id lookup for the Default site. Not just ugly (both the API and the sample code) but will not work with non-default sites. Practically you need to call two functions to log on where the second function gets the same parameter as the first.

Were all of these issues solved in 9.0? Yes, with one small exception.

Tableau REST API in 9.0

From the table above you can see that most of the required functionalities were implemented in 9.0. You can publish to the Server which was the most wanted feature for the API, works for both datasouces and workbooks. You can query groups, users, permissions without the need to connect directly to the repository (which was impossible in larger enterprise multi-tenant deployments).

Pagination in query functions, stream based file uploads, documentations, sample codes? It’s all cool now.

(However, I still cannot trigger a schedule from the API. I know, for me nothing is enough. But surrounded by real life use cases trust me, I know what all of us need.)

What would be the next step?

Generating workbooks and data sources from scratch, obviously. All other market leader tools can generate and modify visualizations and data access layers from API. This is an area where Tableau still weak. I know that it would make a few folks happy (Column, this is for you), but I am not sure that we are just a step away from this.


Tamás Földi

Related items

/ You may check this items as well

sync frelard

Tableau Extensions Addons Introduction: Synchronized Scrollbars

At this year’s Tableau Conference, I tried t...

Read more

Tableau External Services API: Adding Haskell Expressions as Calculations

We all have our own Tableau Conference habits.  M...

Read more
Scaling Tableau Image

Scaling out Tableau Extracts – Building a distributed, multi-node MPP Hyper Cluster

Tableau Hyper Database (“Extract”) is ...

Read more