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, i.e JSON query (which is a list of commands),
• multiple blobs fields that have the raw bytes that need to be transmitted as blobs.

The response will also be multi-part form data and will contain:

• A field called json containing the JSON response
• multiple *blobs fields that have the raw bytes for any blobs being returned

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 Authorizarion header. The command looks like:

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

A successfull response to this command, consists of a session_token and a refresh_token. The value for the session_token is to be used as the token that goes in the Authorizaition header for all authenticated requests.

Example queries.

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