Once you understand the components of the REST request, the key to making the interface useful is understanding what resources are available and what actions you can perform. For the VoltDB Management interface, there are five types of resources you can operate on:

You specify the type of resource as part of the URL. For example, /man/api/1.0/mgmt/databases refers to database resources. To act on a specific resource, you include the resource's internal ID in the URL. So, for example, the following command deletes the database with the internal ID of "154":

curl -X DELETE http://voltdbmgr:8080/man/api/1.0/mgmt/databases/154

For any given resource, there can be up to four methods you can apply to the resource:

Section A.2, “VoltDB Management Interface: Reference Section” explains which methods are possible for each resource type and what arguments are required to perform a POST or PUT.

In addition, there are special actions possible for database resources only. For the database itself, the actions are START, STOP, PAUSE, RESUME, and SNAPSHOT. You can also perform a START and STOP on individual servers assigned to a database.

Since there are no equivalent HTTP methods for these actions, you invoke them by specifying the action as part of the URL and use the HTTP PUT method. For example, the following command starts the database identified by the ID 236:

curl -X PUT http://voltdbmgr:9000/man/api/1.0/mgmt/databases/236/start

When you use the VoltDB Management Interface, the REST services can return information to your program or script in several different ways. The three most important pieces of information the REST interface returns are the status code, any error messages if the request failed, and the return data when the request succeeds.

The REST interface uses standard HTTP response status codes to indicate the success or failure of requests. The specific return code depends upon the action requested. Table A.1, “REST Success Codes” describes the status codes that are returned when a call to the REST interface succeeds.

As noted in the tables, the information returned by the response also depends upon the action requested. For GET methods, the information is returned in the body of the response as a JSON-encoded string. For successful POST actions, the URL for the created resource is returned in the redirect location in the HTTP header.

If a request fails, the VoltDB interface returns both an error status using the HTTP code and a detailed description of the error in the body of the response. The return status depends on the nature of the failure. Table A.2, “REST Error Codes” describes the status codes that are returned when a call to the REST interface fails.

Note that the header, including the status code, is separate from the standard content of the response. You may need to use special arguments to capture the header in the output. For example, the following curl command uses the -w (write-out) argument to include the HTTP code in the output:

curl -w "Code: %{http_code}\n" http://castor:9000/man/api/1.0/mgmt/servers

The best way to understand an interface is often to see it in action. The following are some examples of Linux shell scripts that use the VoltDB Management interface to create and manage databases.

The following script creates the necessary servers, deployment, and catalog resources to define and start a database. In this case, it uses a script routine (RestAdd) to create each of the resources and return the resulting resource ID.

Note the use of the curl -w argument to write the redirect location as part of the output so the script can capture the resource ID created by the REST service. This is necessary since the ID is not in the body of the HTTP resource. An alternative approach is to use -L to have curl follow the redirection. In which case the full JSON representation of the new resource, including the ID, will be in the body of the response.

#
# Sample script to create database.
#
MGTHOST="http://voltdbmgr:9000"
RestAdd () {
  ID=$( curl -sw "%{redirect_url}" -d "$2" \
          "$MGTHOST/man/api/1.0$1" \
          | grep -oP "(?<=$1/)[0-9]+" )
  echo "$ID"
}

# Define Three servers
JSON='{"Server":{"host":"goneril","name":"goneril"}}'
S1=$( RestAdd "/mgmt/servers" "$JSON" )
JSON='{"Server":{"host":"regan","name":"regan"}}'
S2=$( RestAdd "/mgmt/servers" "$JSON" )
JSON='{"Server":{"host":"cordelia","name":"cordelia"}}'
S3=$( RestAdd "/mgmt/servers" "$JSON" )

# Define a deployment
JSON='{"Deployment":{"name":"Flight deployment"}}'
D1=$( RestAdd "/mgmt/deployments" "$JSON" )

# Load a catalog (use base64-encoding)
CATALOG=$( base64 flight.jar )
JSON="{\"Catalog\":{\"name\":\"flight\",\
       \"catalogbytes\":\"$CATALOG\"}}"
C1=$( RestAdd "/mgmt/catalogs" "$JSON" )
 
# Define and start database
JSON="{\"Database\":{\"name\":\"Flight DB\",\
      \"catalog\":\"$C1\",\"deployment\":\"$D1\",\
      \"remotedir\":\"flightdb\",\
      \"Servers\":[{\"server\":\"$S1\"},\
      {\"server\":\"$S2\"},{\"server\":\"$S3\"}]}}"
DB=$( RestAdd "/mgmt/databases" "$JSON" )
curl -X PUT "$MGTHOST/man/api/1.0/mgmt/databases/$DB/start"