Tableau’s REST API allows us to communicate with Tableau Server and ask it to perform tasks on data sources, projects, workbooks, users and sites.
Rest is a common pattern for making requests to and getting responses from an API over the web. We make a REQUEST about a RESOURCE that we want to take an action on, and get a RESPONSE back.
There are many tasks that can be performed with the REST API, and they are all listed here. As this blog is just about getting started, we will not cover all of these and will instead focus on submitting simple requests in order to:
Sign into the Site
Retrieve the list of projects on the site and create a new one
Retrieve the list of users on the site and create a new one
Retrieve the list of user groups on the site, create a new group, and assign a user to it
There are many ways of interacting with the Rest API but in this tutorial, we are going to be using Postman to submit our requests.
Sign into your Site and Get Started
To sign into a site on your Tableau Server, a POST request is needed with a URI in the format below. You’ll find the API version of your server here in the table.
https://MY_SERVER/api/api-version/auth/signinThe following code also has to be entered in the body of your request, using the “raw” option.
<credentials name="user-name" password="password">
<site contentUrl="site-name" />
</tsRequest>Here is an example of a sign in request, where I’ve added in my own details.
Example of a sign in request
When this is sent, the response should look something like this.
Example of a response to a sign in request
A response code of 200 shows that the request was a success. The token and Site ID will need to be noted for all subsequent requests. This token will be used as a means of authentication (until it expires and a new sign in request is needed).
A good way of storing these values is to create an environment and add them as variables. To do this, click on “New” then on “Environment” and give it a name. You can add variables immediately in this step or initially create the environment without them. To add new variables once your environment has been created, click on the eye in the top right corner, then on “Edit”. I’ve stored them as “Token” and “Site_id”.
Creating a new environment
Adding new variables to your environment
Retrieve a list of Projects and create a new one
To retrieve a list of the projects on your site, a GET request is used in the format below. This, and authentication, is all that is needed as GET requests don’t require a message body.
To authenticate, we use the token that was returned to us in the sign in step. This is added in the Headers section under the name “X-Tableau-Auth”.
Below is an example of this request. The variables that I created for site ID and Token are enclosed in curly brackets.
Example of a request to list the projects on the site
To create a new project, we use a POST request with the same URI and header as in the previous step. This time though, we need a body and and this should be in the following format:
description="project description" />
Example of a request to create a new project
Retrieve a list of Users and create a new one
We retrieve the list of Users on the site the same way as we did for projects, except the resource is now “users”. Again, no body is needed but make sure to add the authentication as before.
Below is an example of a response to this request. Nicolas’ details are highlighted for use later when we will add him to a group.
Example of a response to a request to list the users on the site
Creating a new user is described in more detail here, but for now we’ll just look at adding a basic user. If you’re using tableau online then you need to make sure that the username is an email address. The URI is the same as above when retrieving a list of users, and the body should be in the following format:
Example of a request to create a new user
Create a New User Group and Assign a User to it
To create a new user group, a POST request is used in the format below.
https://MY_SERVER/api/api-version/sites/site-id/groups Creating a user group is described in more detail here. We are going to create a local group and so the following body format will be used:
siteRole = "site-role"/>
Example of a request to create a new user group
Example of a response to a request to create a new user group
To assign a user to a group, a POST request is used in the format below.
The body will look something like this:
siteRole = "site-role"/>
The Group ID highlighted in the previous response has been stored as a variable called “sales_group”, and Nicolas’ ID from earlier has been stored as “user_nicolas”, so these can be used in our request to add Nicolas to the Sales Group.
Example of a request to add a user to a group
I hope this has inspired you to get started with it. Have fun!
Join the Data Jam
92% of companies fail to scale their analytics, which likely includes you. We have studied the patterns in hundreds of client engagements and cracked the code for a modern data stack that guarantees success.
We'll uncover this in the most original webinar you've attended this year.