2.2. JSON 応答形式の理解

GET を使用して API に呼び出しを行うと、JSON 形式で結果が返されます。Python json.tool モジュールにかけると、人間がより判読しやすい形式で出力されます。

コレクション用の JSON 応答形式

コレクションとは、ホストやドメインなどのオブジェクトの一覧のことです。コレクションの JSON 応答は、メタデータのフィールドの後に結果セクションが表示される形式です。以下の例は、API ルート GET /api/domains を使用した場合のドメイン一覧のコレクション JSON 応答形式です。出力は、結果セクションがより簡単に確認できるように json.tool でパイプしています。 
$ 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"
        }
    ]
}
応答のメタデータのフィールドの説明は以下のとおりです。
  • total — 検索パラメーターなしのオブジェクトの合計数
  • subtotal — 検索パラメーターを指定して返されたオブジェクト数 (検索がない場合には、累計は合計と同じになります)
  • page — ページ数
  • per_page — ページごとに返す最大数
  • limit — コレクションの応答で返すオブジェクトの指定数
  • offset — コレクションを返す前に省略するオブジェクト数
  • search — scoped_scoped の構文をベースにした検索文字列
  • sort
    • by — コレクションをソートするためのフィールド
    • order — ソート順 (ASC は昇順、DESC は降順)
  • results — オブジェクトのコレクション

単一オブジェクトの JSON 応答形式

単一オブジェクトの JSON 応答を使用して、単一オブジェクトを表示します。GET 要求には、オブジェクトの一意識別子 :id または :name が必要です。:name は一意識別子として常に使用できるわけではありませんが、:id は常に使用できる点に注意してください。単一オブジェクトの JSON 応答形式には、オブジェクトの属性のみが含まれます。
以下の例は、API ルートの GET /api/domains/23 または GET /api/domains/qa.lab.example.com を使用時の単一オブジェクト JSON 応答形式です。 
$ 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"
}