HTTP API

RPC over HTTP

Decthings uses RPC (remote procedure calls) for all API calls. Each HTTP request represents one RPC request.

The HTTP request should be sent to the url https://api.decthings.com/v0/<sub-api-name>/<method-name>.

The HTTP path represents the sub-API and method to use. For example, to call the method "evaluate" within the "model" sub-API:

POST https://api.decthings.com/v0/model/evaluate

Response status code 404 means that the sub-API or method was not found. On success, the response status code will be 200, and status code 500 means the method failed for some reason.

Authorization

To access your private resources such as models and datasets, you first need to create an API key. Then, to include it in your HTTP request:

Set the header Authorization to the value Bearer <myapikey>

where you replace <myapikey> with your own API key.

HTTP body

There a two ways of encoding the body - as a binary version, which is more efficient, or as a text-based utf-8 version, which is more human-readable. Applications should use the binary version, but when for example copying and pasting things it can be easier to use the text-based version.

HTTP body - binary version

To use the binary version:

• Set the header Content-type to the value application/octet-stream.

We will now define what to include in the binary body.

First, we define a varint. A varint is a way to encode an integer so that small values take up less space. In this protocol, a 64-bit unsigned varint which encodes the 64-bit unsigned integer x is defined as:

• If x < 253: Encode a single byte with value x.
• Otherwise, if x < 2^16: Encode a single byte with value 253 followed by a 16-bit big-endian unsigned integer with value x.
• Otherwise, if x < 2^32: Encode a single byte with value 254 followed by a 32-bit big-endian unsigned integer with value x.
• Otherwise: Encode a single byte with value 255 followed by a 64-bit big-endian unsigned integer with value x.

For example, the value x = 18 would be encoded as the byte sequence [18]. The value x = 819 would be encoded as the byte sequence [253 3 51], because [3 51] is the 16-bit byte sequence for 819.

The request body and the response body is split into one or more segments, which we call blobs (binary large objects).

For client to server, the first byte of the HTTP body encodes the number of blobs minus one. Then, the lengths of each blob is added, encoded as 64-bit unsigned integers. Finally, the data of each blob is added.

For server to client, the blobs are placed after one another, but with the length of each blob encoded as a 64-bit unsigned varint placed before each blob.

For both the request and response, the first blob must be UTF-8 JSON. For the request, it must be a JSON object containing the parameters to pass to the function. For the response, the JSON will be of the following format:

{
    // Present if successful
    result?: any
    // Present if failed
    error?: any
}

What the rest of the blobs contains depends on the method used.

HTTP body - text version

To use the text version:

• Set the header Content-type to the value application/json.

The body should contain JSON data, of the following format:

{
    // Parameters to pass to the method
    params: any,
    // Blobs, base64 encoded (A-Z, a-z, 0-9, + and /).
    data?: string[]
}

The response will also be application/json, of the following format:

{
    // Present if successful
    result?: any
    // Present if failed
    error?: any
    // Blobs, base64 encoded (A-Z, a-z, 0-9, + and /).
    data: string[]
}