Starburst Enterprise REST API#

The Starburst Enterprise platform (SEP) REST API allows you to manage the following features with the scripting and automation tool of your choice:

View the reference documentation for the SEP API.

Initial setup#

The REST API can be used to programmatically create entities at any time in the lifecycle of your cluster. However, it is particularly useful during initial setup, when you must create a large number of entities all at once.

Specifically the initial configuration must include creation of a user with the sysadmin role, since it is required to use the REST API. Create the user through the UI, and then use it for further API requests for the initial setup. This can then include further users, that have access to the REST API.

Authentication#

The REST API supports the same authentication methods as the Starburst Enterprise web UI, with the exception of Kerberos authentication.

API clients pass credentials via the Authorization header (either Basic or Bearer type).

Basic authentication#

For PASSWORD authentication, use basic authentication with username and password.

Send the authorization header with the base64-encoded value of username:password:

curl ... -H 'Authorization: Basic dFHzdDp0ZXN0'

Alternatively, specify the username and password with the -u option:

curl ...  -u  'username:password'

Bearer token authentication#

For other authentication methods, use Bearer token authentication. The Bearer token value is the same as the authentication cookie used by the Starburst Enterprise web UI:

curl ... -H 'Authorization: Bearer <token_value>'

Authorization#

The API uses privileges defined in built-in access control. To specify the role to use for their requests, users must send the X-Trino-Role header with the same value as the system role they want to enable. For example, X-Trino-Role : system=ROLE{roleName}

All operations performed with the API are subject to the granted and denied privileges of the role used for the calls. For example, you can only drop a role via the REST API endpoint if the roles used for the API call has the DROP privilege for role entities. Refer to the privileges documentation for the built-in access control for more details.

The following example displays a cURL command to retrieve a specific data product with the identifier 2f86c60f from the API:

curl --location \
     -X GET 'https://sep.example.com/api/v1/dataProduct/products/2f86c60f' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'X-Trino-Role: system=ROLE{sysadmin}' \
     -H 'Authorization: Basic dFHzdDp0ZXN0'

The result is a JSON document that represents the data product as an entity.

  • --location ensures redirects are followed.

  • -X GET URL sets the HTTP command, such as GET or POST for the specified URL.

  • The accept and content type header values define the format for submitted and received data, and are required to use JSON. Depending on the HTTP command used, these headers are not required.

  • Setting the role is optional since all roles are enabled by default. Only using the sysadmin role requires setting the X-Trino-Role header value. Other roles can be set if desired.

  • The authorization header value is used with the base64-encoded value of username:password.

Entities and endpoints#

The REST API is split up into two separate groups of entities and endpoints, detailed in the following sections.

Built-in access control and data products#

Use the detailed technical documentation about all available endpoints and methods, that cover functionality for built-in access control as well as data products:

A full OpenAPI specification for the REST API is available on the server at the api/v1/openApi endpoint.

Code examples include cURL, Java, Android, Obj-C, JavaScript, C#, PHP, Perl, and Python.

Starburst Warp Speed#

A separate REST API for Starburst Warp Speed is available. It uses the same authentication and authorization, but includes a separate set of endpoints. These endpoints use a separate context for each catalog.