This blog post is Human-Centered Content: Written by humans for humans.

The package I’ve been building throughout this series is a simple API for calling REST API’s against your ThoughtSpot cluster. Let’s walk through how to use it!

Requirements

This package is built to be used in Laravel applications and requires PHP 8.2. You’ll need the URL of a ThoughtSpot cluster, a username with privileges to perform the actions your app is designed to use, and a password for the user or a secret key for token auth.

Installation

composer require interworks/thoughtspotrest

Configuration

Next, add the following required environment variables to your .env file:

THOUGHTSPOT_REST_URL="https://YOUR-ORG.thoughtspot.cloud" 
THOUGHTSPOT_REST_USERNAME="YOUR_USER"

Then, depending on your desired authentication, add these:

• “Basic” authentication:

THOUGHTSPOT_REST_AUTH_TYPE="basic" 
THOUGHTSPOT_REST_PASSWORD="YOUR_USER_PASSWORD"

• “Trusted” authentication:

THOUGHTSPOT_REST_AUTH_TYPE="trusted" 
THOUGHTSPOT_REST_SECRET_KEY="123abc-..."

• “Cookie” authentication:

THOUGHTSPOT_REST_AUTH_TYPE="cookie" 

THOUGHTSPOT_REST_PASSWORD="YOUR_USER_PASSWORD"

Documentation

Every REST API call in ThoughtSpot’s documentation has a function to call it with the same name in camel case. For instance, the “Search Metadata” API call can be called with:

$ts->searchMetadata($args);

ThoughtSpot’s REST API documentation can be found here.

Usage Guide

The package is installed and configured! Now for the good stuff. Let’s instantiate a ThoughtSpotREST object and start making calls!

use InterWorks\ThoughtSpotREST\ThoughtSpotREST; 
 
// Instantiate 
$ts = new ThoughtSpotREST(); 
 
// Get first 10 Liveboards and create a collection. 
$liveboards = $ts->searchMetadata(['metadata' => ['type' => 'LIVEBOARD'], 'record_size' => 10]); 
$liveboards = collect($liveboards); 
 
// Get a user by name and update it 
$users = $ts->searchUsers(['user_identifier' => 'jlyons', 'record_size' => 1]); 
$user = collect($users)->first(); 
$userID = $user['id']; 
$ts->updateUser($userID, ['email' => 'justin.lyons@interworks.com']);

The code above shows how to do a few basic actions. All API endpoints should be supported by the package. But sometimes those pesky platforms will add endpoints and not inform me personally. In these cases, you can use the call function as a canvas to send whatever REST API you need that the package doesn’t support:

$response = $ts->call( 
    url: 'metadata/search', 
    args: ['metadata' => ['type' => 'LIVEBOARD'], 'record_size' => 10], 
    method: 'POST' 
); 
$response->json();

You can specify the endpoint, arguments and method. The package will still handle authentication so you just need to define the call. It’s worth noting that the return type for the call method is an Illuminate\Http\Client\Response object. This function is what’s used internally to make the calls. The package will go the extra step of translating that Response into the assumed desired type. For instance, if you’re retrieving metadata the function will return an array. However, you may want the control of always receiving the Response object. In that case, you can set the returnResponseObject parameter when constructing the ThoughtSpotREST object:

$ts = new ThoughtSpotREST(returnResponseObject: true); 
$response = $ts->searchMetadata(['metadata' => ['type' => 'LIVEBOARD'], 'record_size' => 10]); 
$success = $response->successful(); 
$body = $response->body(); 
$liveboards = $response->json();

The End

Thank you for following along this series and I hope you gained a lot of useful insight! In the spirit of open source, if you see an issue with the package feel free to make a PR to fix it. 😎 InterWorks is interested in creating more packages like this one, so stay tuned. Or if you have an analytics platform with a REST API you’d like a Laravel API for, drop a line and we’ll cook it up.