2.2. Understanding the JSON Response Format

Calls to the API using GET will return results in JSON format. Passing the output through the Python json.tool module gives a more human readable format.

JSON Response Format for Collections

Collections are a list of objects such as hosts and domains. The format for a collection JSON response consists of a metadata fields section followed by a results section. Below is an example of the format for a collection JSON response for a list of domains when using the API route GET /api/domains. The output was piped through json.tool to make the results section easier to read. 
$ curl -X GET -k -u admin:password https://satellite6.example.com/api/domains | python -m json.tool
{
    "total": 3,
    "subtotal": 3,
    "page": 1,
    "per_page": 20,
    "search": null,
    "sort": {
        "by": null,
        "order": null
    },
    "results": [
        {
            "id": 23,
            "name": "qa.lab.example.com",
            "fullname": "QA",
            "dns_id": 10,
            "created_at": "2013-08-13T09:02:31Z",
            "updated_at": "2013-08-13T09:02:31Z"
        },
        {
            "id": 25,
            "name": "sat.lab.example.com",
            "fullname": "SATLAB",
            "dns_id": 8,
            "created_at": "2013-08-13T08:32:48Z",
            "updated_at": "2013-08-14T07:04:03Z"
        },
        {
            "id": 32,
            "name": "hr.lab.example.com",
            "fullname": "HR",
            "dns_id": 8,
            "created_at": "2013-08-16T08:32:48Z",
            "updated_at": "2013-08-16T07:04:03Z"
        }
    ]
}
The response metadata fields are described below:
  • total — The total number of objects without any search parameters.
  • subtotal — The number of objects returned with the given search parameters (if there is no search, then subtotal is equal to total).
  • page — The page number.
  • per_page — The maximum number of objects returned per page.
  • limit — The specified number of objects to return in a collection response.
  • offset — The number of objects skipped before returning a collection.
  • search — The search string based on scoped_scoped syntax.
  • sort
    • by — The field that the collection is sorted by.
    • order — The sort order, either ASC for ascending or DESC for descending.
  • results — The collection of objects.

JSON Response Format for Single Objects

Single-object JSON responses are used to show a single object. The object’s unique identifier, :id or :name, is required in the GET request. Note that :name cannot always be used as a unique identifier, but :id can always be used. The format for a single-object JSON response consists of only the object’s attributes.
Below is an example of the format for a single-object JSON response when using the API route GET /api/domains/23 or GET /api/domains/qa.lab.example.com. 
$ curl -X GET -k -u admin:password https://satellite6.example.com/api/domains/23 | python -m json.tool
{
    "id": 23,
    "name": "qa.lab.example.com",
    "fullname": "QA",
    "dns_id": 10,
    "created_at": "2013-08-13T09:02:31Z",
    "updated_at": "2013-08-13T09:02:31Z"
}