Topics: 9 min readtime

Tableau’s Rest API: Using Postman (The Basics)

Written by Kathryn McCrindle
Wednesday 24 March, 2021

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.

Overview of REST


There are many tasks that can be performed with the REST API, and they are all listed hereAs 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/signin

The 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.

REST Sign in exampleExample of a sign in request

 

When this is sent, the response should look something like this.

REST Sign in response

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”

REST Creating a new environment

Creating a new environment

Save environment option

Add new variables to your 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

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

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

Example of a response to a request to list the users on the site

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>
  <user
name="username"
siteRole="site-role"
  />
</tsRequest>

Example of a request to create a new user

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 request to create a new user group


Example of a response to 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