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 onscoped_scopedsyntax.sortby— 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"
}