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}

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 subtypes 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 subtypes:

    • 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 subtypes:

    • 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 subtypes 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": "UserA@example.com",
  "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": "tsadmin@thoughtspot.com"
    }
  },
  "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🔗