Administration API

Access the API

The Administration API is available on all database nodes. The nodes must be reachable by the client sending the request.

If you have not uploaded a TLS Certificate, configure your client to use insecure server connections when interacting with the API. For example, all curl commands will then require the --insecure or -k option.

The Administration API is defined using the OpenAPI specification (formerly known as Swagger). You can use this specification to generate your own code and use the API in the programming language of your choice. The specification is found at https://<node_ip>/openapi.json.

Authentication

The Administration API supports Basic authentication (BA) with a user name and password. When you deploy Exasol, a user “admin” is created with a password specified by the CCC_PLAY_ADMIN_PASSWORD configuration parameter. For more information, see Configure c4 for AWS.

After deployment, the password can only be changed using the ConfD job user_passwd.

You can create additional users that are able to use the Administration API. These users must belong to the exaadm group. For more information, see Add Users.

When using Basic authentication, an authentication token is added to the Authorization header in the HTTP request. The token is a base64 encoding of a string in the format USER_NAME:PASSWORD containing the credentials of the user that should execute the request. To generate an authentication token, run the following command:

IFS= read -p $'user: \n' USER_NAME && IFS= read -s -p $'password: \n' PASSWORD && echo -n $USER_NAME:$PASSWORD | base64

For example, the user and password admin:exasol corresponds to the authorization token YWRtaW46ZXhhc29s. When creating an HTTP request, you add this token to the request in this way:

-H "Authorization: Basic YWRtaW46ZXhhc29s"

Only users in the exaadm group are able to authenticate in the Administration API.

Swagger UI

The database access node includes a Swagger UI that can be used to generate REST calls for the Administration API. The generated code can then be copied and used in a client connected to the API.

The Swagger UI can be authorized to interact directly with the Administration API. Click on Authorize and enter a valid username and password to enable access. For more information, see Authentication.

The Swagger UI is found at https://<node_ip>/openapi/index.html.

Examples

Example 1: Get databases

This example retrieves a list of databases.

GET request - curl

curl --insecure -X "GET" \
"https://203.0.113.154/api/v1/databases" \
-H "accept: application/json" \
-H "Authorization: Basic YWRtaW46ZXhhc29s"

Response:

[
  {
    "id": "Exasol",
    "name": "Exasol",
    "provider": "aws",
    "version": "8.23.1",
    "ram": 22376,
    "auditing": true,
    "clusters": {
      "total": 1,
      "running": 1
    },
    "dataVolume": "DataVolume1",
    "cloudDataVolume": "DataVolume2",
    "snapshotVolume": "SnapshotVolume",
    "dataVolumeSync": "DataVolume2Sync",
    "snapshotVolumeSync": "SnapshotVolumeSync"
  }
]

GET request - Python

import requests

node_ip = '203.0.113.154'
user = 'admin'
pw = 'exasol'

response = requests.get(
    f'https://{node_ip}/api/v1/databases', 
    auth=(user, pw),
    verify=False
)

print(response.json())

Response:

[{'id': 'Exasol', 'name': 'Exasol', 'provider': 'aws', 'version': '8.23.1', 'ram': 11188, 'auditing': True, 'clusters': {'total': 1, 'running': 1}, 'dataVolume': 'DataVolume1', 'cloudDataVolume': 'DataVolume2', 'snapshotVolume': 'SnapshotVolume', 'dataVolumeSync': 'DataVolume2Sync', 'snapshotVolumeSync': 'SnapshotVolumeSync'}]

Example 2: Stop database

This example stops the database with the name “Exasol”.

PUT request - curl

curl -X 'PUT' \
  'https://203.0.113.154/api/v1/databases/Exasol/stop' \
  -H 'accept: application/json' \
  -H 'Authorization: Basic YWRtaW46ZXhhc29s'

PUT request - Python

import requests

node_ip = '203.0.113.154'
user = 'admin'
pw = 'exasol'

response = requests.put(
    f'https://{access_node_ip}/api/v1/databases/Exasol/stop',
    auth=(user,pw),
    verify=False
    )

print(response.json())

Example 3: Scale cluster size

This example changes the instance type of a worker cluster to “c5d.xlarge”

PUT request - curl

curl --insecure -X "PUT" \
"https://203.0.113.154/api/v1/databases/Exasol/clusters/worker_cluster/scale" \
-H "accept: application/json" \
-H "Authorization: Basic YWRtaW46ZXhhc29s" \
-H "Content-Type: application/json" \
-d '{
  "instanceType": "c5d.xlarge"
}'

PUT request - Python

import requests

access_node_ip = '203.0.113.154'
user = 'admin'
pw = 'exasol'
data = {
  "instanceType": "c5d.xlarge"
}

response = requests.put(
    f'https://{access_node_ip}/api/v1/databases/Exasol/clusters/Exasol/scale',
    auth=(user,pw),
    verify=False,
    json=data
    )