REST API

While a lot of this documentation and sample code from the SDK is focused on interaction with ApertureDB over TCP connection, port 55555, ApertureDB provides an alternate communication modality over HTTP. This is typically made available on a different port, perhaps 443 for HTTPS (recommended) or 80 for HTTP.

All the queries that ApertureDB clients send over TCP can also be sent to ApertureDB over HTTP with RESTish calls. You can also use this interface to build your own client if you are using an unsupported language.

REST Interface to ApertureDB

The REST layer is a very simple wrapper of the TCP endpoint. When an instance of ApertureDB is brought up, it listens on port 80 for REST-based queries.

There is a single endpoint for all the queries, and that is /api/.

From a HTTP client, the type of requests that work are POST methods, transmits the request as a payload, but uses multi-part form data to create message to be sent. The message itself is in the form of

• a field called query, with Content-Type: application/json, containing a JSON query (which is a list of commands)
• zero or more fields called blobs, with Content-Type: application/octet-stream, containing the raw bytes for any blobs required by the commands

The response will be a JSON object containing two fields:

• A field called json, with containing the JSON response array
• A field called blobs, with containing an array of Base64-encoded blobs

Authentication and Authorization

• All the queries made in this manner also rely on a Authorization header with value as Bearer <token> to be accepted by ApertureDB server.
• This <token> is obtained from an Authenticate command to the Server, which is a special type of query that does not need a Authorization header. The command looks like:

{
    "Authenticate": {
        "username": "username",
        "password": "password"
    }
}

A successful response to this command consists of a session_token and a refresh_token. The token returned in session_token should be used in future Authorization headers for all authenticated requests.

Example Queries

In the URL examples below, you can remove the port for default setup.

JavaScript

const request = (query, blobs, handler, sessionToken) => {
    apiURL =  "https://<hostname>:<port>/api/"
    const formData = new FormData();
    formData.append('query', JSON.stringify(query));
    displayContent(query, response=false);

    blobs.forEach(element => {
        formData.append('blobs', element);
    });

    let headers = null;
    if (sessionToken != null){
        console.log(`setting session token ${sessionToken}`);
        headers = {
            "Authorization": `Bearer ${sessionToken}`
        }
    }

    axios.post(
            url=apiURL,
            data=formData, {
                headers: headers
            }).then((response)=>{
                handler(response.data)
            })
}

get_schema = () => {
    //Get a refresh token.
    auth = [{
        "Authenticate": {
            "username": "username",
            "password": "password"
        }
    }]
    request(query = auth, blobs = [], handler = (data)=>{
        authData = data["json"];
        sessionToken = authData[0].Authenticate.session_token;
        query = [{
            "GetSchema" : {

            }
        }]
        request(query=query, blobs=[], handler = (data)=>{
            console.log(data["json"])
        })
    }

get_schema()

Python

import requests
import json

URL = "http://<hostname>:<port>/api/"

def request(query, blobs, session_token=None):
    kwargs = {}
    if session_token:
        kwargs["headers"] = {"Authorization": f"Bearer {session_token}"}
    response = requests.post(URL,
        files = [('query', (None, json.dumps(query)))],
        verify = False, # SSL
        **kwargs)

    if response.status_code != 200:
        raise Exception(response.text)

    return json.loads(response.text)["json"]

def get_schema():
    auth_resp = request(query=[{
        "Authenticate": {
            "username": "<username>",
            "password": "<password>"
        }
    }], blobs=[])
    session_token = auth_resp[0]["Authenticate"]["session_token"]
    print(session_token)
    schema_resp = request(query = [{
        "GetSchema": {}
    }], blobs=[], session_token=session_token)
    print(schema_resp)

get_schema()

bash

HOST=<hostname>
PORT=<port>
USER=<username>
PASSWORD=<password>

resp=`curl ${HOST}:${PORT}/api/ -F query="[{\"Authenticate\": {\"username\":\"$USER\", \"password\":\"$PASSWORD\" }}]" -v`
token=$(echo -n $resp | jq -r .json[0].Authenticate.session_token)

echo "Got token: $token"

curl -H "Authorization: Bearer $token" ${HOST}:${PORT}/api/ -F query="[{\"GetSchema\": { }}]" -v

Resources

The sample reference code is available under rest_api

File	Description	instructions
rest_api.py	Interactions with ApertureDB using python's requests	python rest_api.py
rest_api.js	Interactions with ApertureDB using javascript with axios	Is included in index.html
index.html	A web page that renders from responses from ApertureDB	Tested on chrome