Administration API

Exasol Administration API is a RESTful API that you can use to:

• Manage databases and clusters

• Create new worker clusters

• Create and manage backups

• Manage licenses

• Create volumes

The Administration API is built on top of ConfD. Since the Administration API is RESTful, you can interact with it using a variety of programming languages and interfaces using standard libraries. For more information, see RESTful API by AWS.

Authentication

The Administration API supports Basic authentication with a user name and password. During deployment, a user “admin” is created with a password specified by the CCC_PLAY_ADMIN_PASSWORD parameter in the c4 configuration. After deployment the password for this user can 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.

The user must be assigned to the exaadm group to be able to use the Administration API.

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: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 can add this token to the request. For example:

-H "Authorization: Basic YWRtaW46ZXhhc29s"

Accessing the API

The Administration API is available on the database access node. The endpoint URLs in the REST calls must point to the IP address of the database node.

The Exasol deployment must include an access node if you want to use the Administration API. The access node must be reachable by the client sending the request.

When interacting with the API, configure your client to use insecure server connections unless you uploaded a TLS Certificate. For example, all curl commands require the -k option.

The Administration API specification is defined using the OpenAPI specification (formerly known as Swagger) and is found at https://DATABASE_ACCESS_NODE_IP/openapi.json.

Examples

The following examples returns the list of available databases in curl and in Python.

GET Request - Curl

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

returns:

[
   {
      "clusters" : {
         "running" : 2,
         "total" : 2
      },
      "id" : "Exasol",
      "name" : "Exasol",
      "provider" : "aws"
   }
]

GET Request - Python

import requests

access_node_ip = '203.0.113.154'
user = 'admin'
pw = 'exasol'

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

print(response.json())

returns:

[{'id': 'Exasol', 'name': 'Exasol', 'provider': 'aws', 'clusters': {'total': 2, 'running': 2}}]

The following examples scale a worker cluster to the instance type 'c5d.xlarge'. For more details, see Scale a Cluster.

PUT Request - Curl

curl -k -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
    )