Administration API

Access the API

The Administration API is available on all nodes in a cluster. The client that is used to send requests to the API endpoints must be able to access the nodes. If you have not uploaded a TLS certificate to the system, you must configure the client to use insecure server connections when interacting with the API.

For more information about TLS certificates, see Upload TLS Certificate.

The option --insecure or -k tells curl to bypass the TLS certificate check. This option allows you to connect to a HTTPS server that does not have a valid certificate. Only use this option if certificate verification is not possible and you trust the server.

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 about configuration parameters, see Install Exasol - step by step.

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 about how to add users, 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 in a Linux shell:

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

You will be prompted to enter a user and password, and the output will be the encoded token.

For example, the user admin and the password exasol will be encoded as the authorization token YWRtaW46ZXhhc29s. You can then add this token to each curl request using the -H option:

curl -H "Authorization: Basic YWRtaW46ZXhhc29s"
...

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

Swagger UI

Swagger UI is a visual representation of the Administration API that you can use to generate REST calls, which you can then copy and use in a client. You can also use Swagger UI to interact directly with the Administration API by clicking on Authorize and entering authentication credentials. For more details, see Authentication.

Swagger UI is available on all database nodes at https://<node_ip>:4444/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:4444/api/v1/databases" \
-H "accept: application/json" \
-H "Authorization: Basic YWRtaW46ZXhhc29s"

Response:

[
  {
    "id": "MY_DATABASE",
    "name": "MY_DATABASE",
    "provider": "unknown",
    "version": "8.23.1",
    "ram": 22376,
    "auditing": true,
    "clusters": {
      "total": 1,
      "running": 1
    },
    "dataVolume": "DataVolume1",
    "cloudDataVolume": ""
  }
]

GET request - Python

import requests

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

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

print(response.json())

Response:

[{'id': 'MY_DATABASE', 'name': 'MY_DATABASE', 'provider': 'unknown', 'version': '8.23.1', 'ram': 22376, 'auditing': True, 'clusters': {'total': 1, 'running': 1}, 'dataVolume': 'DataVolume1', 'cloudDataVolume': ''}]

Example 2: Stop database

This example stops the database with the name MY_DATABASE.

PUT request - curl

curl -X 'PUT' \
  'https://203.0.113.154:4444/api/v1/databases/MY_DATABASE/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}:4444/api/v1/databases/MY_DATABASE/stop',
    auth=(user,pw),
    verify=False
    )

print(response.json())