Starburst Galaxy API #

The Starburst Galaxy API allows you to automate processes that are otherwise performed with the user interface. This allows you to manage processes without user interaction, including outside business hours, and to integrate Starburst Galaxy in automated workflows in your overall data pipeline and other business processes.

The API is implemented as a REST API over TLS/HTTPS including the use of authentication tokens. Each token is associated with a role and its privileges that are fully integrated with the Starburst Galaxy security system.

Authentication #

Usage of the API requires an authentication token. These tokens are created and managed in the user interface section available as API auth token in the Access control section of the navigation panel.

Authorization #

Each API authentication token is assigned a role and any operation with the API and the token is restricted and controlled by the access available to the role.

For example, if a role assigned to an API token does not have the privileges to start or stop a cluster, any API calls with that token to perform these actions fail.

Access the API #

To access the API, you must first generate a new API token.

1. Generate the base64 encoded string using the client ID and secret key values from the token you created:

    echo -n CLIENT_ID:SECRET_KEY | base64
   

   Replace CLIENT_ID and SECRET_KEY with the client ID and secret key:

    echo -n uTwiAPLiCZnTjIid:2BCgfvDbJP6o61H5REt9P2FMkEw39chd | base64
   

   Running this command returns the CLIENT_ID and SECRET_KEY encoded in base64.

2. The following cURL example shows an -X POST request:

    curl -X POST \
      -H 'Authorization: Basic PSAIWHLSKDO06Pj34ZEltUW23RFdDS3nKEPUozOX432Szc0NkI1VFlYNXAwDw==' \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -d 'grant_type=client_credentials' \
      https://ACCOUNT_DOMAIN/oauth/v2/token
   

   a. Copy the generated base64 CLIENT_ID:SECRET_KEY string, e.g. PSAIWHLSKDO06Pj34ZEltUW23RFdDS3nKEPUozOX432Szc0NkI1VFlYNXAwDw==, to the Basic Authorization header.

   b. Replace ACCOUNT_DOMAIN with your youraccount.galaxy.starburst.io account domain, which can be found in the URL.

The access token returned is a long string of characters similar to the following:

  eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiItekE0bUFsU1N3M0RHRE1Ddmt...

You can use this access token with the Authorization: Bearer ACCESS_TOKEN header and endpoints to make API calls.

Endpoints #

Any API authentication that is assigned the accountadmin role can use all API endpoints.

The following endpoints for different entities are available:

• Cluster service
  • listClusters - list all clusters
  • startCluster- start the specified cluster
  • stopCluster - stop the specified cluster

Technical documentation for the API is available at https://galaxy.starburst.io/public-api. Each endpoint’s documentation includes the exact URL of the endpoint, details about any parameters, JSON results, and HTTP result codes for success or failure.

The Starburst Galaxy API does not include endpoints for query processing. For more information, see Queries.

Example usage #

Set up to access the API and then use the access token with the listClusters endpoint and the Authorization: Bearer ACCESS_TOKEN header to view all clusters in your account:

  curl https://ACCOUNT_DOMAIN/public/api/v1/cluster
    -H 'Authorization: BEARER eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiItekE0bUFsU1N3M0RHRE1DdmtOYVZEc1dXYms1djNaU2...

The following is the result of a successful request:

  {"nextPageToken":"","result":[{"syncToken":"2","clusterId":"w-3829737466","name":"sample"},{"syncToken":"3","clusterId":"w-9081218528","name":"demodocs"}]}

For easy viewing of the result, you can output into a file:

    curl https://{account-domain}/public/api/v1/cluster \
      -H 'Authorization: BEARER ACCESS_TOKEN' \
      > result.json

Open the file in an editor or a web browser to improve formatting:

    {
      "nextPageToken":""
      "result":[
        {
          "syncToken":"2",
          "clusterId":"w-3829737467",
          "name":"sample"
        }
      ]
    }
    {
        {
          "syncToken":"3",
          "clusterId":"w-9081218528",
          "name":"demodocs"
        }
      ]
    }

Queries #

The Starburst Galaxy API does not provide endpoints for query processing. Each cluster exposes the Trino API for query processing.

Instead of using the Trino API for executing queries, use the recommended client tools and drivers:

• The most convenient client is the query editor, which is a browser-based UI in Starburst Galaxy for running and managing SQL queries.
• You can also use the available wrapper libraries and drivers for query processing with a variety of applications and tools, or for your custom development efforts.

If you really need to build your own client, refer to the Trino client API documentation in the developer guide. Custom implementations are not recommended since other options are available.