Enterprise API Reference

The Enterprise API is a conventional REST API in the sense that it has a number of URI resources that support one or more GET, PUT, POST, or DELETE operations. While reporting is done using SQL, this query is always wrapped in a JSON request.

See Also: Enterprise API Examples

Requests

GET requests are one of listing or getting. Listing resources means that a number of results will be returned, but each entry may contain limited information. An example of a listing query is /api/user to list users. Notice that URI components are always non-plural. An exception to this is /api/settings, which returns the singleton resource for settings. Getting a resource specifies an individual resource to return, e.g. /api/user/homer.

PUT request typically create a new resource, e.g. a user.

POST requests typically updates an existing resource. DELETE requests are also supported in some cases.

Note: When updating objects via the REST API the behavior is to overwrite existing objects. Any missing keys are reset to default values. For example if you have custom LDAP settings and want to update the blueHostHorizon you should first query to get the current settings, and then post the complete settings that you desire else the customized LDAP settings will be reset to defaults.

This example shows using JQ to preserve existing setting when updating an individual key value.

[root@hub]# curl -s -u admin:admin http://localhost:80/api/settings \
| jq '.data[0] + {"blueHostHorizon": 2222, "logLevel": "warning"}' \
| curl -s -u admin:admin http://localhost:80/api/settings -X POST -d @-

[root@hub]# curl -s -u admin:admin http://localhost:80/api/settings | jq '.data[0]'
{
  "blueHostHorizon": 2222,
  "hostIdentifier": "default.sys.fqhost",
  "ldapEnabled": false,
  "ldapEncryption": "plain",
  "ldapHost": "localhost",
  "ldapLoginAttribute": "uid",
  "ldapPort": 389,
  "ldapPortSSL": 636,
  "logLevel": "warning",
  "rbacEnabled": true,
  "sketchActivationAlertTimeout": 60
}

Pagination

Pagination is handled by page and count query parameters to a GET request, e.g. /api/user?page=5&count=30 to get the 5th page of pages with 30 entries each. The default page is 1 and the default count is 50 if these are not specified explicitly.

Responses

Enterprise API responses are always of the following format, consisting of a 'meta' object and a 'data' array.

    {
      "meta": {
        "page": 1,
        "count": 1,
        "total": 1,
        "timestamp": 1350922925
      },
      "data": [
         ...
      ]
    }

page refers to the current page number of the request. count is the number of results in the current page, equaling the length of the data array. total is the number of results in all available pages combined. timestamp is the time the request was processed by the API. The data array is resource dependent, but will always contain objects. Response objects typically do not contain error codes.

If the response is not 200 OK, the appropriate HTTP error code returned along with a (possibly non-JSON) payload.

All timestamps are reported in Unix Time, i.e. seconds since 1970.

Authentication

The API supports both internal and external authentication. The internal users table will always be consulted first, followed by an external source specified in the settings. External sources are OpenLDAP or Active Directory servers configurable through /api/settings.

Authorization

Some resources require that the request user is a member of the admin role. Roles are managed with /api/role. Role Based Access Control (RBAC) is configurable through the settings. Users typically have permission to access their own resources, e.g. their own scheduled reports.