Tableau REST API

In the commonly used command line tool cURL, the REST request to sign in looks like:

curl "https://MY-SERVER/api/3.12/auth/signin" -X POST -d "@signin.xml"

This REST request contains a URI that points to the address of a Tableau user sign in resource: 3.12/auth/signin .

The resource location includes an API version (3.12). When you make a request to a specific API version, you know you will get that version of Tableau behavior, even if that behavior evolves in a future version. For the full story on versioning, see REST API and Resource Versions.

In this case, the request also includes a request body that provides the details of the request. The cURL request above points to an XML file (-d "@signin.xml") that contains the user credentials and the site content URL.

Now that the resource is defined in the URI, and the details Tableau needs are described in the request body, you need to choose an HTTP verb. This tells Tableau what action that resource should use to take. The verb in this request is POST, which tells Tableau to create and return a credentials token.

Common verbs include:

• POST (create) - Create a resource.
• GET (read) - Retrieve a list of a specified kind of resource or the details of a specified resource.
• PUT (update) - Update the properties of a resource, or a list of resources.
• DELETE (delete) - Delete a resource.

There are many ways to make a REST request. You can open a terminal window and type in the cURL command to run the examples provided here. Postman, another common tool for making individual requests, has many features including the ability to make a collection of reusable requests. Each language typically has REST libraries or intrinsic functions that you can use to integrate requests to Tableau.

For Python scripting, you can also access the REST API using the Tableau Server Client (TSC) library. TSC is an open source Python wrapper that allows you to use Tableau REST API methods without dealing with REST call details. Tableau Developer Platform teams often contribute, and new REST methods are typically available in the library in the TSC version that follows their release in the Tableau product. Use the REST API TSC if your code is in Python. and you aren’t calling the very latest methods to be released. Use the REST API directly if you are calling from other languages, or need a very recently released method
 

When you succeed at making the sign in request, the Tableau response looks like:

<tsResponse . . .> <credentials token="W6cRFuYwRKyd50fQuMxebQ|GxSzZnSWOCCHlBW86W3ILBlaukFgmFza" estimatedTimeToExpiration="361:20:45" > <site id="a905dbfd-6550-4546-908b-3e055fcc026d" contentUrl="my_site_name" /> <user id="d5e162f1-6821-422c-a34b-3198eac500e5" /> </credentials> </tsResponse>

Here is an cURL example, of how to use the credentials token and site ID to make a validated request to Tableau. This request creates a new project. The credentials token and site id values are abbreviated for simplicity.

curl "https://MY_SERVER/api/3.12/sites/{{site_id}}/projects" -X POST -H "X-Tableau-Auth:{{credentials_token}}" -d "@create-project.xml"

The credentials token is added to the request header (-H "X-Tableau-Auth:6{{credentials_token}}"), a part of the request that contains metadata related to the characteristics of the request.

create-project.xml contains the request body with the name and description of the new project:

<tsRequest>
    <project
      name="my-new-project-name"
      description="The new project I created to get started!" />
</tsRequest>

The successful response will look like:

<tsResponse . . .>
    <project id="91560c1b-a407-4453-bbf6-8368bf2367df"
      name="my-new-project-name"
      description="he new project I created to get started!"
      createdAt="2021-05-07T22:31:58Z"
      updatedAt="2021-05-07T22:31:58Z"
      contentPermissions="ManagedByOwner">
        <owner id="1b526a10-048b-4d1d-96e7-e12ec7f46388"/>
        </project>
</tsResponse>

The next step depends on the task you want to perform. You might want to add a workbook owned by a specific user to the project using the Update Workbook method. That method requires the LUID of the workbook, so you might first call the Query Workbooks for User method, and parse the workbooks listed in the response to find the right one. To make that request you might need to find the user’s LUID, meaning you would first call Get Users on Site and find the LUID in that response.