REST API

This article describes the REST API in Exasol SaaS.

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, such as: 

  • Manage databases and clusters
  • Manage the network security allowed list
  • Manage and add users

You can interact with the REST API through the Swagger UI or using the command line.

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. For more details, see Using Swagger UI.

swagger ui overview

API Definition

The REST API is documented in the OpenAPI specification , formerly called the Swagger specification. You can read the complete API definition and download the Open API Definition JSON file from the 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. You can use them to authenticate to the REST API as a bearer token in the header. For more information, see Personal Access Token.

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

We recommend that you create personal access tokens only with the required scopes. For example, if you only want to manage the database, select database-operate. For more details, see Scope of personal access tokens.

How to use the REST API

Using the command line

You can interact with the REST API from the command line using curl. You must include the personal access token (PAT) in the curl commands.

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

$ 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