Overview

Authorization

When automatic login is disabled, you must include an Authorization header with a valid API token in every request:

Authorization: Bearer $CDROUTER_API_TOKEN

For example, if a user’s API token is deadbeef, the Authorization header would be:

Authorization: Bearer deadbeef

You can use the Authenticate endpoint to learn a user’s API token by providing the user’s password.

A user’s API token can be found by navigating to /users in CDRouter’s web interface and selecting the user from the list. It is also possible to list the users on your CDRouter system with the following command (requires root access):

/usr/cdrouter/bin/cdrouterd -list-users

When automatic login is disabled, failure to include a valid API token will result in a 401 Unauthorized response. A 401 Unauthorized response is also returned when trying to access a resource that the user is not allowed to view:

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "timestamp": "2016-04-14T10:33:10.728248133-04:00",
    "error": "insufficient privileges"
}

Use the -H switch to add an Authorization header when using cURL:

curl -H "Authorization: Bearer $CDROUTER_API_TOKEN" http://localhost/api/v1/results

Authenticate

Get a user’s API token by authenticating via username/password.

POST /authenticate
Content-Type: application/x-www-form-urlencoded

username=admin&password=cdrouter

Response 200 OK

{
    "timestamp": "2017-06-01T09:01:42.599028514-04:00",
    "data": {
        "id": "1",
        "admin": true,
        "disabled": false,
        "name": "admin",
        "description": "Default admin user",
        "created": "2016-02-04T14:39:21.117867-05:00",
        "updated": "2016-07-11T11:29:24.24582-04:00",
        "token": "deadbeef"
    }
}

Requests/Responses

Requests with a JSON body must include a Content-Type header set to application/json:

Content-Type: application/json

Unless otherwise noted, all request and response bodies should be assumed to be JSON.

For clarity, example URL parameters on these pages are shown in their unescaped form. However, actual requests sent to CDRouter must have proper URL encoded parameters. For example, the unescaped URL parameter ?filter=name=default.conf must be encoded as ?filter=name%3Ddefault.conf.

Receiving a 301 Moved Permanenty response to any request should be considered normal. Clients receiving a 301 response should follow the redirect by resending the request (including any request body from the original request) to the URL in the Location header.

HTTP/1.1 301 Moved Permanently
Location: /api/v1/results/

Successful 2xx JSON responses include a top-level timestamp field containing the server time when the response was generated and a top-level data field containing the response payload:

{
    "timestamp": "2016-04-14T10:33:10.728248133-04:00",
    "data": { ... }
}

Most API errors will result in a non-200 response. The response will include a top-level error field describing the error:

{
    "timestamp": "2016-04-14T10:33:10.728248133-04:00",
    "error": "invalid token"
}

Filtering

Many listing API calls can take one or more ?filter URL parameters to narrow what is returned. The syntax for each parameter is ?filter=[NAME][OP][VALUE] where NAME is the field to filter on and OP is a valid comparison operator for that field. A ?type URL parameter with possible values inter or union controls how multiple filters are combined (AND’d or OR’d). If not specified, ?type is assumed to be inter.

Each field’s set of operators is determined by its type:

String Field Operators

Integer/Date Field Operators

Boolean Field Operators

Array Field Operators

For example, the following cURL command would return results created between 6/16/15 and 6/20/15:

curl -Ls -H "Authorization: Bearer $CDROUTER_API_TOKEN" -G \
--data-urlencode 'filter=created>2015-06-16' \
--data-urlencode 'filter=created<2015-06-20' http://localhost/api/v1/results

or to list results which are tagged with both foo and bar:

curl -Ls -H "Authorization: Bearer $CDROUTER_API_TOKEN" -G \
--data-urlencode 'filter=tags@>{foo,bar}' http://localhost/api/v1/results

or to list the union of results which contain either the tag foo or the testcase cdrouter_basic_1:

curl -Ls -H "Authorization: Bearer $CDROUTER_API_TOKEN" -G \
--data-urlencode 'type=union' \
--data-urlencode 'filter=tags@>{foo}' \
--data-urlencode 'filter=testcases@>{cdrouter_basic_1}' http://localhost/api/v1/results

Sorting

Similarly, many listing API calls can take a ?sort URL parameter to change the ordering of what is returned. The syntax for the ?sort parameter is ?sort=+/-NAME[,+/-NAME].... NAME is a field to sort on. A + indicates ascending ordering while - means descending ordering. Multiple sort fields can be specified by separating with commas.

For example, the following cURL command would return results, sort first by creation time (ascending) then by size (descending) and finally user ID (ascending):

curl -Ls -H "Authorization: Bearer $CDROUTER_API_TOKEN" -G
--data-urlencode 'sort=+created,-size_on_disk,+user_id' http://localhost/api/v1/results

Paging

Some API calls page results so as not to overwhelm the client with a large response. The ?limit parameter is used to specify how many results to return in each page. The ?page parameter is used to specify which page of the results to return. The last page of results can be returned by setting ?page to last. In addition to the top-level data field which contains the current page’s data, a top-level links field is returned with the following fields allowing easy navigation of paged results:

{ 
    "data": {
        ...
    },
    "links": { 
        "first": 1,
        "prev": 3,
        "current": 5,
        "next": 6,
        "last": 8,
        "total": 100
    }
}

Where first, prev, current, next and last are the first, previous, current, next and last page numbers, respectively. The total field indicates the total number of resources across all pages. Paging can be disabled by setting ?limit to none, in which case everything will be returned in a single response.

For example, to retrieve page 3 of /api/v1/results when asking for 25 results per page, use the following cURL command:

curl -Ls -H "Authorization: Bearer $CDROUTER_API_TOKEN" -G
--data-urlencode 'page=3' --data-urlencode 'limit=25' http://localhost/api/v1/results

Summary / Detailed Representations

Fetching a list of resources returns a response which often includes only a subset of fields for those resources and is known as the summary representation. Fetching an individual resource returns a response which includes all fields for that resource and is known as the detailed representation. Please note that while a field may not be present in the summary representation of a resource, that field can still be used in ?filter and ?sort parameters.

API calls which return a list of resources can be modified to return the detailed representation and therefore return all fields for that resource by setting the ?detailed parameter to true. Please note that this can result in an extremely large response, especially if used with a ?limit parameter of none, and therefore should be used with care.