REST API v1 and v2.0 comparison

REST API v1 and v2.0 comparison

Both v1 and v2 REST API frameworks allow you to access, retrieve, create, and manage ThoughtSpot objects and resources. REST API v2.0 is a new framework that expands the core API functionality with additional features and improved user experience.

Feature comparison🔗

FeatureREST API v1REST API v2.0

API Playground

Go to Develop > REST API > REST API v1 Playground.

REST API v1 endpoints can be accessed via Swagger API explorer.

Go to Develop > REST API > REST API v2.0 Playground.

Playground access

Requires admin or developer privilege

Requires admin or developer privilege

Downloadable code samples

–

✓

API documentation

✓ Developer Documentation

✓ API Playground Help

✓ Developer Documentation

Authentication support

✓ Basic authentication

✓ Trusted authentication

✓ Basic authentication

✓ Bearer token authentication

✓ Trusted authentication

Request and Response structure

Not fully standardized

Standardized

API services

See Supported API operations

See Supported API operations

Resource URL

Base URI
https://{your-thoughtspot-hostname}/callosum/v1/
Resource path
tspublic/v1/{resource-group}/{resource}/

Base URI
https://{your-thoughtspot-hostname}/
Resource path
/api/rest/2.0/{resource-group}/{resource}

Supported API operations🔗

API serviceREST API v1REST API v2.0

Admin services
API endpoints for cluster-level administration

✓ Available

✓ Available

Available under system
Includes query APIs only

Authentication
API endpoints for user login, authentication, and session management

✓ Available

The login, authentication, token generation, and logout services are available under session.

✓ Available

Data APIs
Data query APIs for searching data from a data source and querying a Liveboard and its visualization data.

✓ Available

✓ Available

Connection and live query services API endpoints for CRUD operations of data connection objects

✓ Available

✓

Database services
Data management API services for databases such as Falcon

Applicable to ThoughtSpot Software deployments only

✓ Available

–

Dependency services
API endpoints for querying dependent object details.

✓ Available

✓ Available

Available as part of metadata API operations.

Groups
API endpoints for group administration and management

✓ Available

✓ Available

Liveboard export
API for downloading Liveboard and visualizations data as PDF

✓ Available

✓ Available

This API service is available under report.

Logs
API for audit logs
Applicable to ThoughtSpot Cloud deployments only

✓ Available

✓ Available

Materialization services
API endpoint for refreshing a materialized view.

Applicable to ThoughtSpot Software deployments only

✓ Available

–

Metadata services

API for querying metadata objects, assigning tags, setting favorites, and importing and exporting TML objects

✓ Available

The metadata API service does not support fetching SQL query information from Answer and Liveboard objects

✓ Available

Supports fetching SQL query information from Answer and Liveboard objects
Includes API services for importing and exporting TML representation of metadata objects such as Liveboard, Worksheets, and Answers__

Orgs
API endpoints for Org administration and management

✓ Available

✓ Available

Reports
API endpoints for downloading Liveboards and Answers in PDF, PNG, XLS, or CSV format.

✓ Available

The Answer download API service is not available

✓ Available

Session
API endpoints for user login, authentication token generation, default Liveboard assignment, and user logout.

✓ Available

✓ Available

The login, authentication, token generation, and logout services are available as session resource and are listed under the Authentication category in the Playground.

Security
API endpoints for sharing objects and assigning permissions.

✓ Available

✓ Available

System
API endpoints for querying system information

✓ Available

The system administration API operations are available as Admin services

✓ Available

TML
API endpoints for importing and exporting TML representation of metadata objects

✓ Available

✓ Available

The import and export metadata API service is available under *metadata*.

User
API endpoints for user administration and management

✓ Available

✓ Available

Version control
API endpoints for Git integration and version control

– Not Available

✓ Available

Schedules
API endpoints to schedule and manage Liveboard jobs.

– Not Available

✓ Available

Request methods🔗

REST API v1REST API v2.0

  • GET for query APIs

  • POST for create operations. API calls that support multiple fields for filtering data also use the POST method.

  • PUT for update operations

  • DELETE for delete operations

Some GET and DELETE operations support query and path parameters, whereas the POST and PUT calls require a JSON request body.

  • POST
    In REST API v2.0 framework, most of the API operations require you to use the POST method.

  • GET
    For some API operations, such as querying system information or session information, you can use the GET method.

Object types and naming convention🔗

The following table lists the metadata object types and sub-types supported in REST API v1 and REST API v2.0:

REST API v1REST API v2.0

Metadata object types in REST API v1:

  • QUESTION_ANSWER_BOOK for Answers

  • PINBOARD_ANSWER_BOOK for Liveboards

  • LOGICAL_TABLE for a Table, Worksheet, or View.
    Includes the following sub-types:

    • ONE_TO_ONE_LOGICAL for tables

    • WORKSHEET for worksheets.

    • USER_DEFINED for data imported by users

    • AGGR_WORKSHEET for views

  • TAG for tag objects

  • DATA_SOURCE for data source objects

  • USER for user objects

  • USER_GROUP for user group objects

  • LOGICAL_COLUMN for a column of any data object such as tables, worksheets, or views

  • LOGICAL_RELATIONSHIP for table or worksheet joins

    The LOGICAL_COLUMN and LOGICAL_RELATIONSHIP metadata types include the following sub-types:

    • FORMULA to query a list of formulas applied to a worksheet column

    • CALENDAR_TYPE to query the type of calendar used by the DATE TYPE column in a worksheet

    • CALENDAR_TABLE to query columns that have a custom calendar configured

Metadata object types in REST API v2.0:

  • LIVEBOARD for Liveboards

  • ANSWER for saved Answer object

  • CONNECTION for data connections

  • TAG for tag objects

  • USER for user objects

  • USER_GROUP for groups

  • LOGICAL_TABLE for Table, Worksheet, or View.

  • LOGICAL_COLUMN for a column of any data object such as tables, worksheets, or views.

  • LOGICAL_RELATIONSHIP for table and worksheet joins

Querying metadata objects by sub-types is not supported in the current release.

Request and response structure🔗

In REST API v2.0, the API endpoints let you pass several request parameters in a single API call. User and group administration and metadata query APIs support several distinct operations.

The following example shows the REST API v1 and v2 endpoints available for user administration and provisioning:

REST API v1 and v2 comparison

Although the REST API v2.0 has fewer endpoints, it supports all user administration and CRUD operations that were available with REST API v1.

Request body🔗

The following example shows the API v1 and v2 request body for user creation operation:

REST API v1

POST /tspublic/v1/user/

curl -X POST \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Accept: application/json' \
-d 'name=UserA&password=GuestTest123!&displayname=User A&properties={ "userContent": {"userPreferences": {"showWalkMe": true}}}&groups=["d0326b56-ef23-4c8a-8327-a30e99bcc72b"]&usertype=LOCAL_USER&visibility=DEFAULT&triggeredbyadmin=true' \
'https://{ThoughtSpot-Host}/callosum/v1/tspublic/v1/user/'
REST API v2.0

POST /api/rest/2.0/users/create

curl -X POST \
  --url 'https://{ThoughtSpot-Host}/api/rest/2.0/users/create' \
  -H 'Authorization: Bearer {OAUTH_TOKEN}'\
  -H 'Accept: application/json'\
  -H 'Content-Type: application/json' \
  --data-raw '{
  "name": "UserB",
  "display_name": "User B",
  "password": "123Cloud!",
  "email": "[email protected]",
  "account_type": "LOCAL_USER",
  "account_status": "ACTIVE",
  "group_identifiers": [
    "ADMINISTRATOR"
  ],
  "visibility": "SHARABLE",
  "show_onboarding_experience": true,
  "notify_on_share": true,
  "home_liveboard_identifier": "eee701ad-10d2-4bd5-b268-e07c123569c8",
  "favorite_metadata": [
    {
      "identifier": "59a8ae34-3609-4385-9f6b-871b74c901a3",
      "type": "LIVEBOARD"
    },
    {
      "identifier": "beb2344c-215b-46a0-b518-3e933365bfc2",
      "type": "ANSWER"
    }
  ]
}'

Response structure🔗

REST API v1REST API v2.0

API response for GET /tspublic/v1/user/:

{
  "userContent": {
    "userPreferences": {
      "notifyOnShare": true,
      "showWalkMe": true,
      "analystOnboardingComplete": false,
      "numTimesDisplayNameDialogShown": 1,
      "preferredLocale": "en-US"
    },
    "userProperties": {
      "persona": "BUSINESS_USER",
      "mail": "[email protected]"
    }
  },
  "state": "ACTIVE",
  "assignedGroups": [
    "d0326b56-ef23-4c8a-8327-a30e99bcc72b",
    "b25ee394-9d13-49e3-9385-cd97f5b253b4"
  ],
  "inheritedGroups": [
    "d0326b56-ef23-4c8a-8327-a30e99bcc72b",
    "b25ee394-9d13-49e3-9385-cd97f5b253b4"
  ],
  "privileges": [],
  "type": "LOCAL_USER",
  "parenttype": "USER",
  "visibility": "DEFAULT",
  "tenantId": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
  "displayName": "Administrator",
  "header": {
    "id": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "indexVersion": 55,
    "generationNum": 55,
    "name": "tsadmin",
    "displayName": "Administrator",
    "author": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
    "created": 1354006445722,
    "modified": 1674640734259,
    "modifiedBy": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "owner": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "isDeleted": false,
    "isHidden": false,
    "clientState": {
      "preferences": {
        "sageDataSource": [
          "540c4503-5bc7-4727-897b-f7f4d78dd2ff"
        ],
        "homePinboardId": "b2d68a4f-cf67-4723-966f-8a592fdbf8b9",
        "SAGE_SEARCH_BUTTON_TOUR_SEEN": true
      },
      "parameters": {
        "parametersIntroSplashScreenAppearanceCount": 5
      },
      "tips": {
        "navBarHelpTip": true
      }
    },
    "belongToAllOrgs": true,
    "tags": [],
    "type": "LOCAL_USER",
    "isExternal": false,
    "isDeprecated": false,
    "isSharedViaConnection": false
  },
  "complete": true,
  "incompleteDetail": [],
  "isSuperUser": false,
  "isSystemPrincipal": true
}

API response for POST /api/rest/2.0/users/search

[
  {
    "id": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "name": "tsadmin",
    "display_name": "Administrator",
    "visibility": "SHARABLE",
    "author_id": "0f0dd0f7-7411-4195-a4aa-0dc6b58413c9",
    "can_change_password": true,
    "complete_detail": true,
    "creation_time_in_millis": 1354006445722,
    "current_org": {
      "id": 0,
      "name": "Primary"
    },
    "deleted": false,
    "deprecated": false,
    "account_type": "LOCAL_USER",
    "account_status": "ACTIVE",
    "email": "",
    "expiration_time_in_millis": 1674636710,
    "external": false,
    "favorite_metadata": [],
    "first_login_time_in_millis": 1638322388839,
    "group_mask": 6,
    "hidden": false,
    "home_liveboard": null,
    "incomplete_details": [],
    "is_first_login": false,
    "modification_time_in_millis": 1674608622609,
    "modifier_id": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "notify_on_share": true,
    "onboarding_experience_completed": false,
    "orgs": null,
    "owner_id": "59481331-ee53-42be-a548-bd87be6ddd4a",
    "parent_type": "USER",
    "privileges": [
      "ADMINISTRATION",
      "AUTHORING",
      "USERDATAUPLOADING",
      "DATADOWNLOADING",
      "DATAMANAGEMENT",
      "SHAREWITHALL",
      "A3ANALYSIS"
    ],
    "show_onboarding_experience": true,
    "super_user": false,
    "system_user": true,
    "tags": [],
    "tenant_id": "982d6da9-9cd1-479e-b9a6-35aa05f9282a",
    "user_groups": [
      {
        "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b",
        "name": "Administrator"
      }
    ],
    "user_inherited_groups": [
      {
        "id": "d0326b56-ef23-4c8a-8327-a30e99bcc72b",
        "name": "Administrator"
      }
    ],
    "welcome_email_sent": false
  }
]

Related information🔗