Chapter 11. Tungsten REST API (APIv2)

Each cluster process listens for API calls using the following ports by default:

Should you wish to choose your own ports for the API, this can be handled by specifying the new ports in the tpm config using the following properties:

connector-rest-api-port=8096
manager-rest-api-port=8090
replicator-rest-api-port=8097

With our focus on security in the first release of the API, without any user created, only ping and createAdminUser calls will be available. tpm makes it easy to create the administration user at install through the following options:

rest-api-admin-user=tungsten
rest-api-admin-pass=secret

Once an admin user is created, all other APIs call will be available using basic HTTP authentication with that user/password.

If you haven't created the user as part of the initial cluster installation, you can use the Dashboard GUI to do this for you during Dashboard configuration, or use the CLI calls explained below.

Using CURL commands

The createAdminUser call will allow creation and modification of REST API users.

shell> curl -k -H 'Content-type: application/json' --request POST 'https://127.0.0.1:8096/api/v2/createAdminUser?i-am-sure=true' \
> --data-raw '{
>   "payloadType": "credentials",
>   "user":"tungsten",
>   "pass":"security"
> }'

{ "payloadType":"StringPayload",
  "payloadVersion":"1",
  "payload":{ 
      "value":"https://127.0.0.1:8096/api/v2/user/tungsten"
            }
}

Using tapi

The tapi tool can make the creation of the admin user simple and straightforward, the following example shows the use of this approach.

shell> tapi --create --host hostnamehere --create-user usernamehere --create-password passwordhere -v

SSL is enabled by default and will use the same keystore, certificates and aliases as the cluster TLS ones.

You can specify them with java-tls-keystore-path and java-truststore-path tpm options, or let tpm generate the certificates for you during installation.

For more detailed information on SSL, see Chapter 5, Deployment: Security

As previously mentioned, the API is enabled by default, listening only on localhost.

To disable the API, you will need to specify the following tpm options:

replicator-rest-api=false 
manager-rest-api=false 
connector-rest-api=false

To change the address that the API is listening on, you need to specify the following tpm options:

replicator-rest-api-address=0.0.0.0
connector-rest-api-address=0.0.0.0
manager-rest-api-address=0.0.0.0

curl is the simplest command line tool to access the API.

Note that in the examples below, we use self signed certificates, which is why the -k flag is passed to cURL

Ping command

shell> curl -k --request GET 'https://127.0.0.1:8096/api/v2/ping'

{ "payloadType":"PingPayload",
  "payloadVersion":"1",
  "payload":{
      "message":"Ping test",
      "date":"Mon Sep 20 11:48:48 CEST 2021",
      "hostName":"gilmbp-8.local",
      "pid":16743,
      "jvmUptime":152513
      }
}

In this example, we sent a simple ping. Result comes as an HTTP OK response with a payload containing a string message “ping test”, the date of execution, the hostname of the executor and its pid, plus the number of milliseconds elapsed since the java executable was started

Create admin user

shell> curl -k -H 'Content-type: application/json' --request POST 'https://127.0.0.1:8096/api/v2/createAdminUser?i-am-sure=true' \
> --data-raw '{
>   "payloadType": "credentials",
>   "user":"tungsten",
>   "pass":"security"
> }'

{ "payloadType":"StringPayload",
  "payloadVersion":"1",
  "payload":{ 
      "value":"https://127.0.0.1:8096/api/v2/user/tungsten"
            }
}

This POST request show how input data can be passed to API calls as a json string.

In return, the createAdminUser function will give a link to the API call allowing you to display details for the user we just created. Let’s follow this link:

shell> curl -k --request GET 'https://127.0.0.1:8096/api/v2/user/tungsten' -utungsten:security

{ "payloadType":"CredentialsPayload",
  "payloadVersion":"1",
  "payload":{
      "user":"tungsten",
      "pass":"**obfuscated**",
      "access":"full"
            }
}

This call shows how the user/password tuple is passed.

The equivalent call using base64 encoded Authorization header, obtained with echo -ne "tungsten:security" | base64 would look something like the following:

shell> curl -k --request GET 'https://127.0.0.1:8096/api/v2/user/tungsten' --header 'Authorization: Basic dHVuZ3N0ZW46c2VjdXJpdHk='

  "payload":{
      "user":"tungsten",
      "pass":"**obfuscated**",
      "access":"full"
            }
}

tapi is a convenient command line tool developed by Continuent that will ease access to Tungsten components APIs without having to remember full REST call URLs.

Full documentation on tapi can be found here: Section 9.22, “The tapi Command”

PostMan is one of the most popular GUI tools for REST API testing and use

Tungsten API defines its own payloads for both inputs and output. The generic structure looks like the following:

{
   "payloadType": "TypeOfPayload",
   "payloadVersion": "1",
   "payload": 
   {
     "key"="value"
   }
}

Where payloadType announces the type of data that will be contained in payload in the given payloadVersion

As an example, a very simple payload is found in the StringPayload data structure and only consists in a key/value pair:

{
   "payloadType": "StringPayload",
   "payloadVersion": "1",
   "payload": 
   {
      "string"="stringvalue"
   }
}

When starting up with a fresh installation of tungsten, if no admin user has been provided to tpm, credentials can be sent to the various functions via the following payload

{
    "payloadType": "CredentialsPayload",
    "payload":
    {
     "user":"<user>",
     "pass":"<password>"
    }
}

The same payload structure, slightly enriched, will be found in response to listing the user via:

{
    "payloadType": "CredentialsPayload",
    "payloadVersion": "1",
    "payload": {
        "user": "tungsten",
        "pass": "<obfuscated>",
        "access": "full"
    }
}

Various other payloads used and produced by Tungsten REST API entry point will be found in the detailed technical documentation. Links below: