/avatars_200px_circle_Kathryn_McCrindle.png){kind=avatar}
Introduction
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.<tsRequest><credentials name="user-name" password="password"><site contentUrl="site-name" /></credentials></tsRequest>Here is an example of a sign in request, where I’ve added in my own details.
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.
https://MY_SERVER/api/api-version/sites/site-id/projects
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:
<tsRequest><project name="new-project-name" description="project description" /></tsRequest>
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. https://MY_SERVER/api/api-version/sites/site-id/users
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:
<tsRequest> <username="username"siteRole="site-role" /></tsRequest>
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:
<tsRequest><group name="group-name"siteRole = "site-role"/></tsRequest>
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.
https://MY_SERVER/api/api-version/sites/site-id/groups/group-id/users
The body will look something like this:
<tsRequest>
<user id="user-id"
siteRole = "site-role"/>
</tsRequest>
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!
- Kathryn
Empower your organization with intuitive analytics
Tableau is designed to put the user first because data analysis should be about asking questions and not about learning software. With built-in visual best practices, Tableau enables limitless visual data exploration without interrupting the flow of analysis.
As the market-leading choice for modern business intelligence, the Tableau platform is known for taking any kind of data from almost any system and turning it into actionable insights with speed and ease. It’s as simple as dragging and dropping.
We are a full-stack provider and integrator, relying on extensive experience and best practices to find your unique optimal set-up allowing you to tell the data stories you are eager to tell.
