REST API

This article describes the REST API in Exasol SaaS.

Introduction

Exasol SaaS provides a REST API that allows you to use RESTful commands to carry out most of the operations that are available in the web console. You can interact with the REST API through the built-in Swagger UI , with a command line tool such as curl, or using an API client such as Postman or Insomnia.

Definitions of all endpoints in the REST API can be found in the Exasol SaaS OpenAPI specification .

Swagger UI

Swagger UI is an interactive API console that allows you to generate commands that you can copy and use in other interfaces. Many commands can also be executed directly from the Swagger UI after authenticating.

swagger ui overview

For more details, see Using Swagger UI.

Authentication

To use the REST API, you must first generate a personal access token (PAT). Personal access tokens function like regular OAuth access tokens. When interacting with the REST API on the command line or with an API client, you must add the token in the request header.

We recommend that you create personal access tokens with only the scopes that are required. For example, if you only want to manage the database, choose the scope Database - use & operate.

To learn more about how to create a PAT and about token scopes, see Personal access token.

For security reasons, you can only create a personal access token from the web console.

How to use the REST API

Using the command line

To use the REST API on the command line or with an API client, you must generate a personal access token (PAT) and then add the token in the header of the REST call.

For example, the following command will return the databases from account sd1Eks1bSY22B6eNL2T0jw:

Copy 
$ curl -X GET "https://cloud.exasol.com/api/v1/accounts/sd1Eks1bSY22B6eNL2T0jw/databases" -H "accept: application/json" -H "Authorization: Bearer <your-personal-access-token>"
[
  {
    "id": "5df0HVAcTuWY4xkoBvgzcA",
    "name": "Database01",
    "clusters": {
      "total": 1,
      "running": 0
    },
    "provider": "AWS",
    "region": "eu-central-1",
    "usedStorage": 0,
    "createdAt": "2021-05-21T10:18:54",
    "createdBy": "00umiyjw8OXBtXQ2O416",
    "status": "tocreate"
  }
]

For more information about using different programming languages and interfaces to send RESTful commands, see RESTful API by AWS.

Using Swagger UI

Swagger UI is an interactive API console that allows you to generate commands that you can copy and use in other interfaces. Many commands can also be executed directly from the Swagger UI.

To use Swagger UI to generate and execute REST commands you must first authenticate using your personal access token (PAT).

  1. Open Swagger UI.

  2. Click on the Authorize button.

    authorize in swagger ui

  3. Enter your personal access token as the BearerAuth value and click on Authorize.

    This dialog does not confirm if you have entered a correct PAT.

  4. Click on Close to close the dialog and continue, or click on Logout to cancel authentication.

    authorized with pat

To log out, click on Authorize to open the dialog again and click on Logout.

For security reasons, the authentication is not saved in the browser. If you refresh the browser page you must authorize again.

When you have authenticated you can use SwaggerUI to generate or send REST commands to the different endpoints.

To enable a REST command, click on Try it out and enter the required values.

using swagger ui