2.2. Understanding the JSON Response Format
Calls to the API return results in JSON format. The API call returns the result for a single-option response or for responses collections.
JSON Response Format for Single Objects
You can use single-object JSON responses to work with a single object. API requests to a single object require the object’s unique identifier :id.
This is an example of the format for a single-object request for the Satellite domain which ID is 23:
Example request:
$ curl --request GET --insecure --user sat_username:sat_password \ https://satellite.example.com/api/domains/23 | python -m json.tool
Example response:
{
"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"
}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 and a results section.
This is an example of the format for a collection request for a list of Satellite domains:
Example request:
$ curl --request GET --insecure --user sat_username:sat_password \ https://satellite.example.com/api/domains | python -m json.tool
Example response:
{
"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
API response uses the following metadata fields:
-
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. sort-
by— Specifies by what field the API sorts the collection. -
order— The sort order, either ASC for ascending or DESC for descending.
-
-
results— The collection of objects.