API Reference

API Reference

Endpoints

The JackDB API is organized around the following high-level endpoints and resources:

• API Information
• Backup
• Data Sources
• History
• People
• Permissions
• Query
• Roles
• Search
• Snippets

Clients

Client must address requests to the hostname for their JackDB server. The same hostname that clients use to connect to the JackDB web interface should be used.

Clients must specifiy a User-Agent header. Requests with a blank User-Agent header will be rejected.

Clients must specify an Accept: application/vnd.jackdb.v2+json header.

HTTPS

All API requests must occur over HTTPS.

Authentication

All API requests must be authenticated. Authentication is done using HTTP Authorization header using Basic authentication.

The username is your API key id suffixed with @api. The password is your API secret.

Endpoint Prefix

For the current version of the API, all endpoints are prefixed with /api/v2.

cURL Examples

Examples are provided using the cURL command-line tool to demonstrate the requests to and responses from the various API endpoints. Parameter values are represented as ${PARAMETER} so that you can control and replace them via environment variables.

The examples below assume the following environment variables have been defined. You’ll need to replace them with their equivalents for your JackDB environment.

After creating an API key from the web interface, you can find the same values for your JackDB installation by viewing the details of a newly created API key.

export JACKDB_API_URL="https://jackdb.example.com/api/v2"
export JACKDB_API_KEY_ID="423a2940-a1c5-40db-8c3f-9900641e2b36"
export JACKDB_API_KEY_SECRET="Xcn2DbmQflnDSPLFPXfnVxMS4QKZsCzR"

Responses

All API responses are returned as JSON. Whenever possible, HTTP status codes reflecting the response will be returned. Successful responses will return a 200 status code, rejected requests (including authentication errors) will return 40X status codes, and internal server errors will return 50X status codes.

Error response bodies are of the form:

{
    error: {
        message: <string>
    }
}

Common Field Names & Data Types

The following fields have the same semantic meaning, regardless of the object type to which they refer:

• id - string : The unique identifier of an object
• createdAt - timestamp : The timestamp when the object was created
• updatedAt - timestamp : The timestamp when the object was last updated

The id field will remain constant throughout the life of an object.

Timestamp fields are always represented in ISO-8601 format. For example: 2014-07-31T18:09:58.637Z

Request Bodies

The following Content-Type headers are allowed for request bodies:

• JSON
  • Must have a Content-Type: application/json header.
• URL Encoded Form Data
  • Must have a Content-Type: application/x-www-form-urlencoded header.

Note: Regardless of the format of the request body, API responses will always be returned as JSON.

Unique Identifiers

API endpoints that refer to an individual object (e.g., Person, Data Source) can be referenced by any unique identifier for that object. All objects include a unique id. Additionally, most objects include additional fields that may be unique as well.

To use a non-id field to refer to an object, prefix the field name with a colon (:) in the request path.

For example, if a person has an id of P123456789, a username of alice, and an email of alice@example.com, then the following are equivalent and reference the same API endpoint:

• /api/v2/person/P123456789
• /api/v2/person/username:alice
• /api/v2/person/email:alice@example.com