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 on scoped_scoped syntax.
  • 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.