<dependency>
<groupId>io.github.thoughtspot</groupId>
<artifactId>rest-api-sdk-lib</artifactId>
<version>2.14.0</version> <!-- Use the latest version available -->
<scope>compile</scope>
</dependency>
Java SDK for REST APIs
The REST API Java SDK provides a client library to interact with ThoughtSpot REST API v2 endpoints from Java applications.
Before you begin🔗
Before you begin, check if your setup meets the following requirements:
-
Your application setup has the necessary tools and environments for installing, deploying, and testing the SDK integration.
-
The REST API Java SDK library supports Java 8 and later. Ensure that your environment has Java 8 or later installed.
-
You have access to the necessary repositories on GitHub and Maven Central and network permissions download dependencies.
-
You have a ThoughtSpot instance with access to v2 REST APIs.
For token-based authentication, you’ll need access to the secret key. -
User privileges and object permissions to view, edit, or create ThoughtSpot objects and resources.
Import the SDK to your application environment🔗
If you are using Maven, add the REST API Java SDK as a dependency to the POM.xml file in your project:
If you are using Gradle, add the REST API Java SDK as a dependency to your build file:
repositories {
mavenCentral()
}
dependencies {
implementation "io.github.thoughtspot:rest-api-sdk-lib:2.14.0"
// Use the latest version of the SDK
}
API client configuration🔗
The ApiClientConfiguration class in the REST API Java SDK allows configuring the settings required for API clients to call REST APIs from their application context. Use this class to specify any of the following methods and parameters:
-
basePath
- Sets the base path for API requests. -
bearerToken
- Sets bearer tokens to authenticate API requests. -
bearerTokenSupplier
- Sets the bearer token supplier for authentication. -
defaultHeader
- Adds a default header to API requests. -
defaultHeaderMap
- Sets a map of default headers to include in the API requests. -
defaultCookie
- Adds a default cookie to the client configuration. -
defaultCookieMap
- Sets a map of default cookies in the client configuration. -
verifyingSsl
- Enables Secure Sockets Layer (SSL) certificate verification for API requests. -
sslCaCert
- Configures the client to use a specific input stream that contains the SSL CA certificate. -
keyManager
- Adds a key manager to the client configuration. -
keyManagers
- Adds a list of key managers to the client configuration. -
downloadPath
- Sets the download path for files. -
connectTimeoutMillis
- Sets the connection timeout. -
readTimeoutMillis
- Configures the maximum number of seconds the client will wait for a response after sending a request before timing out. -
writeTimeoutMillis
- Configures the maximum number of milliseconds the client will wait for the data to be written to the server after sending a request before timing out.
// Create configuration for the ThoughtSpot API client
ApiClientConfiguration apiClientConfiguration = new ApiClientConfiguration.Builder()
.basePath(BASE_PATH) // Your ThoughtSpot application URL
.verifyingSsl(false) // Disable SSL verification for testing purposes
.readTimeoutMillis(30000) // Extended read timeout to 30 seconds
.build();
Authentication🔗
The REST API v2.0 supports various authentication methods. The most common method used for automation and application integration is the token-based authentication. To get a token from from authentication token endpoint, you need to specify the username
and password
or secret_key
.
The following example shows the code for getting an authentication token by passing username
and password
, and creating a user session using this token:
package org.example;
// Import classes:
import com.thoughtspot.client.ApiClientConfiguration;
import com.thoughtspot.client.ApiException;
import com.thoughtspot.client.api.ThoughtSpotRestApi;
import com.thoughtspot.client.model.GetFullAccessTokenRequest;
import com.thoughtspot.client.model.Token;
import com.thoughtspot.client.model.User;
public class Example {
private static final String BASE_PATH = *CLUSTER_URL*; // Your ThoughtSpot application URL
private static final String USERNAME = "tsUserA"; // Username
private static final String PASSWORD = "Your-Password"; // Password
public static void main(String[] args) {
try {
// Create configuration for the ThoughtSpot API client
ApiClientConfiguration apiClientConfiguration = new ApiClientConfiguration.Builder()
.basePath(BASE_PATH)
.verifyingSsl(false) // Disable SSL verification for testing purposes
.readTimeoutMillis(30000) // Extended read timeout to 30 seconds
.build();
// Create an instance of the ThoughtSpot API client
ThoughtSpotRestApi tsRestApi = new ThoughtSpotRestApi(apiClientConfiguration);
// Authenticate the user and retrieve the full access token
GetFullAccessTokenRequest getFullAccessTokenRequest = new GetFullAccessTokenRequest()
.username(USERNAME)
.password(PASSWORD);
Token response = tsRestApi.getFullAccessToken(getFullAccessTokenRequest);
// Update the API client configuration with the access token
apiClientConfiguration = apiClientConfiguration.toBuilder()
.bearerTokenSupplier(response::getToken) // You can pass your own token supplier here
.build();
// Apply the updated configuration to the ThoughtSpot API client
tsRestApi.applyApiClientConfiguration(apiClientConfiguration);
// Current user information
User currentUser = tsRestApi.getCurrentUserInfo();
System.out.println("Current User: " + currentUser.toJson());
// Optionally, use .{REQUEST}WithHttpInfo() to get response details
ApiResponse<User> currentUserResponse = tsRestApi.getCurrentUserInfoWithHttpInfo();
System.out.println("Current User: " + currentUserResponse.getData().toString());
System.out.println("Status code: " + currentUserResponse.getStatusCode());
System.out.println("Response headers: " + currentUserResponse.getHeaders().toString());
} catch (ApiException e) {
System.err.println("Exception when calling ThoughtSpot API");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
You can also obtain a token by sending username
and secret_key
in your authentication token request. The secret key is generated when Trusted authentication is enabled on your instance and can be viewed on the Develop > Security Settings page.
The following example shows the code for getting an authentication token by passing username
and secret_key
, and creating a user session using this token:
package org.example;
// Import classes:
import com.thoughtspot.client.ApiClientConfiguration;
import com.thoughtspot.client.ApiException;
import com.thoughtspot.client.api.ThoughtSpotRestApi;
import com.thoughtspot.client.model.GetFullAccessTokenRequest;
import com.thoughtspot.client.model.Token;
import com.thoughtspot.client.model.User;
public class Example {
private static final String BASE_PATH = *CLUSTER_URL*; // Your ThoughtSpot application URL
private static final String USERNAME = "tsUserA"; // Username
private static final String SECRET_KEY = "YOUR_SECRET_KEY"; // Secret key generated for your instance
public static void main(String[] args) {
try {
// Create configuration for the ThoughtSpot API client
ApiClientConfiguration apiClientConfiguration = new ApiClientConfiguration.Builder()
.basePath(BASE_PATH)
.verifyingSsl(false) // Disable SSL verification for testing only
.readTimeoutMillis(30000)
.build();
// Create an instance of the ThoughtSpot API client
ThoughtSpotRestApi tsRestApi = new ThoughtSpotRestApi(apiClientConfiguration);
// Authenticate the user and retrieve the full access token using secret_key
GetFullAccessTokenRequest getFullAccessTokenRequest = new GetFullAccessTokenRequest()
.username(USERNAME)
.secretKey(SECRET_KEY); // Use secretKey. Do not use password
Token response = tsRestApi.getFullAccessToken(getFullAccessTokenRequest);
// Update the API client configuration with the access token
apiClientConfiguration = apiClientConfiguration.toBuilder()
.bearerTokenSupplier(response::getToken)
.build();
// Apply the updated configuration to the ThoughtSpot API client
tsRestApi.applyApiClientConfiguration(apiClientConfiguration);
// Current user information
User currentUser = tsRestApi.getCurrentUserInfo();
System.out.println("Current User: " + currentUser.toJson());
} catch (ApiException e) {
System.err.println("Exception when calling ThoughtSpot API");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
Create a test API request🔗
Make a test API call to test the integration and verify the response.
In this example, we’ll use the CreateUserRequest
object to create a user.
package org.example;
import com.thoughtspot.client.ApiClientConfiguration;
import com.thoughtspot.client.ApiException;
import com.thoughtspot.client.api.ThoughtSpotRestApi;
import com.thoughtspot.client.model.CreateUserRequest;
import com.thoughtspot.client.model.User;
public class AddUserExample {
private static final String BASE_PATH = *CLUSTER_URL*; // Your ThoughtSpot application instance
private static final String BEARER_TOKEN = "YOUR_AUTH_TOKEN"; // Token obtained from ThoughtSpot to authorize your API calls
public static void main(String[] args) {
try {
// Configure the API client with the bearer token
ApiClientConfiguration apiClientConfiguration = new ApiClientConfiguration.Builder()
.basePath(BASE_PATH)
.bearerTokenSupplier(() -> BEARER_TOKEN)
.verifyingSsl(false) // For testing only; enable SSL in production
.readTimeoutMillis(30000)
.build();
// Create an instance of the ThoughtSpot API client
ThoughtSpotRestApi tsRestApi = new ThoughtSpotRestApi(apiClientConfiguration);
// Build the user creation request
CreateUserRequest createUserRequest = new CreateUserRequest()
.name("[email protected]")
.displayName("User A")
.password("StrongPassword123!") // Set an initial password
.groupIdentifiers(Arrays.asList("sales", "marketing")) // Optional: assign groups
.addOrgIdentifiersItem(Org_ID); // Optional: set Org ID if using a multi-tenant instance
// Create the user
User createdUser = tsRestApi.createUser(createUserRequest);
// Output the created user details
System.out.println("User created: " + createdUser.toJson());
} catch (ApiException e) {
System.err.println("Exception when calling ThoughtSpot API");
System.err.println("Status code: " + e.getCode());
System.err.println("Reason: " + e.getResponseBody());
System.err.println("Response headers: " + e.getResponseHeaders());
e.printStackTrace();
}
}
}
Error handling🔗
The SDK raises an exception when an API request fails. Inspect the HTTP status code, response body, and response headers to determine the cause of the failure and respond appropriately. Catching exceptions is a standard way to handle these errors. The code samples in this document show how to handle errors using the ApiException
class.
Supported versions🔗
Note the recommendation of Java SDK:
ThoughtSpot release version | Supported SDK version |
---|---|
ThoughtSpot Cloud: 10.9.0.cl | v2.14.0 or later |
ThoughtSpot Cloud: 10.10.0.cl | v2.15.0 or later |
SDK Reference🔗
Method | HTTP request |
---|---|
POST /api/rest/2.0/users/activate | |
POST /api/rest/2.0/security/metadata/assign | |
POST /api/rest/2.0/tags/assign | |
POST /api/rest/2.0/users/change-password | |
POST /api/rest/2.0/vcs/git/branches/commit | |
POST /api/rest/2.0/metadata/worksheets/convert | |
POST /api/rest/2.0/metadata/copyobject | |
POST /api/rest/2.0/vcs/git/config/create | |
POST /api/rest/2.0/connection/create | |
POST /api/rest/2.0/ai/conversation/create | |
POST /api/rest/2.0/customization/custom-actions | |
POST /api/rest/2.0/orgs/create | |
POST /api/rest/2.0/roles/create | |
POST /api/rest/2.0/schedules/create | |
POST /api/rest/2.0/tags/create | |
POST /api/rest/2.0/users/create | |
POST /api/rest/2.0/groups/create | |
POST /api/rest/2.0/dbt/dbt-connection | |
POST /api/rest/2.0/dbt/generate-sync-tml | |
POST /api/rest/2.0/dbt/generate-tml | |
POST /api/rest/2.0/dbt/search | |
POST /api/rest/2.0/users/deactivate | |
POST /api/rest/2.0/vcs/git/config/delete | |
POST /api/rest/2.0/connection/delete | |
POST /api/rest/2.0/connections/{connection_identifier}/delete | |
POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/delete | |
POST /api/rest/2.0/dbt/{dbt_connection_identifier}/delete | |
POST /api/rest/2.0/metadata/delete | |
POST /api/rest/2.0/orgs/{org_identifier}/delete | |
POST /api/rest/2.0/roles/{role_identifier}/delete | |
POST /api/rest/2.0/schedules/{schedule_identifier}/delete | |
POST /api/rest/2.0/tags/{tag_identifier}/delete | |
POST /api/rest/2.0/users/{user_identifier}/delete | |
POST /api/rest/2.0/groups/{group_identifier}/delete | |
POST /api/rest/2.0/vcs/git/commits/deploy | |
POST /api/rest/2.0/connections/download-connection-metadata-changes/{connection_identifier} | |
POST /api/rest/2.0/report/answer | |
POST /api/rest/2.0/report/liveboard | |
POST /api/rest/2.0/metadata/tml/export | |
POST /api/rest/2.0/metadata/tml/export/batch | |
POST /api/rest/2.0/metadata/answer/data | |
POST /api/rest/2.0/metadata/answer/sql | |
POST /api/rest/2.0/metadata/tml/async/status | |
POST /api/rest/2.0/connections/fetch-connection-diff-status/{connection_identifier} | |
POST /api/rest/2.0/metadata/liveboard/data | |
POST /api/rest/2.0/metadata/liveboard/sql | |
POST /api/rest/2.0/logs/fetch | |
POST /api/rest/2.0/security/principals/fetch-permissions | |
POST /api/rest/2.0/security/metadata/fetch-permissions | |
POST /api/rest/2.0/users/force-logout | |
GET /api/rest/2.0/auth/session/user | |
GET /api/rest/2.0/auth/session/token | |
POST /api/rest/2.0/auth/token/custom | |
POST /api/rest/2.0/auth/token/full | |
POST /api/rest/2.0/auth/token/object | |
GET /api/rest/2.0/system/config | |
GET /api/rest/2.0/system | |
GET /api/rest/2.0/system/config-overrides | |
POST /api/rest/2.0/metadata/tml/import | |
POST /api/rest/2.0/metadata/tml/async/import | |
POST /api/rest/2.0/groups/import | |
POST /api/rest/2.0/users/import | |
POST /api/rest/2.0/auth/session/login | |
POST /api/rest/2.0/auth/session/logout | |
POST /api/rest/2.0/ai/analytical-questions | |
POST /api/rest/2.0/users/reset-password | |
POST /api/rest/2.0/vcs/git/commits/{commit_id}/revert | |
POST /api/rest/2.0/auth/token/revoke | |
POST /api/rest/2.0/vcs/git/commits/search | |
POST /api/rest/2.0/vcs/git/config/search | |
POST /api/rest/2.0/connection/search | |
POST /api/rest/2.0/customization/custom-actions/search | |
POST /api/rest/2.0/searchdata | |
POST /api/rest/2.0/metadata/search | |
POST /api/rest/2.0/orgs/search | |
POST /api/rest/2.0/roles/search | |
POST /api/rest/2.0/schedules/search | |
POST /api/rest/2.0/tags/search | |
POST /api/rest/2.0/groups/search | |
POST /api/rest/2.0/users/search | |
POST /api/rest/2.0/ai/conversation/{conversation_identifier}/converse | |
POST /api/rest/2.0/security/metadata/share | |
POST /api/rest/2.0/ai/answer/create | |
POST /api/rest/2.0/tags/unassign | |
POST /api/rest/2.0/vcs/git/config/update | |
POST /api/rest/2.0/connection/update | |
POST /api/rest/2.0/connections/{connection_identifier}/update | |
POST /api/rest/2.0/customization/custom-actions/{custom_action_identifier}/update | |
POST /api/rest/2.0/dbt/update-dbt-connection | |
POST /api/rest/2.0/metadata/headers/update | |
POST /api/rest/2.0/metadata/update-obj-id | |
POST /api/rest/2.0/orgs/{org_identifier}/update | |
POST /api/rest/2.0/roles/{role_identifier}/update | |
POST /api/rest/2.0/schedules/{schedule_identifier}/update | |
POST /api/rest/2.0/system/config-update | |
POST /api/rest/2.0/tags/{tag_identifier}/update | |
POST /api/rest/2.0/users/{user_identifier}/update | |
POST /api/rest/2.0/groups/{group_identifier}/update | |
POST /api/rest/2.0/vcs/git/branches/validate | |
POST /api/rest/2.0/auth/token/validate |