From 2c31869bbcf089e2129670fa497a5f6061f42c45 Mon Sep 17 00:00:00 2001 From: "sonu.kumar" Date: Wed, 16 Mar 2016 18:38:59 +0900 Subject: [PATCH] Adds missing metadata section to API docs Change-Id: I69cb32cec696f11cab908cadbead49ea8698a788 Closes-bug: #1532852 --- doc/source/rest/v2/collections.rst | 330 +++++++++++++++++------------ doc/source/rest/v2/recordsets.rst | 88 ++++---- doc/source/rest/v2/zones.rst | 78 ++++--- 3 files changed, 283 insertions(+), 213 deletions(-) diff --git a/doc/source/rest/v2/collections.rst b/doc/source/rest/v2/collections.rst index 44adb5d69..215625f6b 100644 --- a/doc/source/rest/v2/collections.rst +++ b/doc/source/rest/v2/collections.rst @@ -46,42 +46,54 @@ Links { "zones": [{ "status": "ACTIVE", - "description": null, - "updated_at": "2014-07-08T20:28:31.000000", - "ttl": 86400, - "serial": 1404851315, - "id": "a4e29ed3-d7a4-4e4d-945d-ce64678d3b94", - "name": "example.com.", - "created_at": "2014-07-08T20:28:19.000000", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "version": 1, - "project_id": "noauth-project", - "email": "hostmaster@example.com", + "masters": [], + "name": "example1.org.", "links": { - "self": "http://dns.provider.com/v2/zones/a4e29ed3-d7a4-4e4d-945d-ce64678d3b94" - } - }, - { - "status": "ACTIVE", - "description": null, - "updated_at": null, + "self": "http://dns.provider.com:9001/v2/zones/bd1b954e-69cd-4a91-99b4-0bcc08533123" + }, + "transferred_at": null, + "created_at": "2016-03-14T05:41:49.000000", + "pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "updated_at": "2016-03-14T07:33:49.000000", + "version": 10, + "id": "bd1b954e-69cd-4a91-99b4-0bcc08533123", "ttl": 3600, - "serial": 1405435099, - "id": "13db810b-917d-4898-bc28-4d4ee370d20d", - "name": "abc.example.com.", - "created_at": "2014-07-15T14:38:19.000000", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "version": 1, - "project_id": "noauth-project", + "action": "NONE", + "attributes": {}, + "serial": 1457940809, + "project_id": "54c3cc0b8e21491f820fc701b83cb7fb", + "type": "PRIMARY", "email": "hostmaster@example.com", + "description": null + }, + { "status": "ACTIVE", + "masters": [], + "name": "example.com.", "links": { - "self": "http://dns.provider.com/v2/zones/13db810b-917d-4898-bc28-4d4ee370d20d" - } - }], - "links": { - "self": "https://dns.provider.com/v2/zones?limit=2", - "next": "https://dns.provider.com/v2/zones?limit=2&marker=13db810b-917d-4898-bc28-4d4ee370d20d" - } + "self": "http://dns.provider.com:9001/v2/zones/45fd892d-7a67-4f65-9df0-87273f228d6c" + }, + "transferred_at": null, + "created_at": "2016-03-14T07:50:38.000000", + "pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "updated_at": "2016-03-14T07:50:43.000000", + "version": 2, + "id": "45fd892d-7a67-4f65-9df0-87273f228d6c", + "ttl": 3600, + "action": "NONE", + "attributes": {}, + "serial": 1457941838, + "project_id": "54c3cc0b8e21491f820fc701b83cb7fb", + "type": "PRIMARY", + "email": "hostmaster@example.com", + "description": null + }], + "links": { + "self": "http://dns.provider.com:9001/v2/zones?limit=2", + "next": "http://dns.provider.com:9001/v2/zones?limit=2&marker=45fd892d-7a67-4f65-9df0-87273f228d6c" + }, + "metadata": { + "total_count": 2 + } } Pagination and Sorting @@ -304,27 +316,34 @@ Filtering { "zones": [{ "status": "ACTIVE", - "description": null, - "updated_at": "2014-07-08T20:28:31.000000", - "ttl": 86400, - "serial": 1404851315, - "id": "a4e29ed3-d7a4-4e4d-945d-ce64678d3b94", + "masters": [], "name": "example.com.", - "created_at": "2014-07-08T20:28:19.000000", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "version": 1, - "project_id": "noauth-project", - "email": "hostmaster@example.com", "links": { - "self": "http://dns.provider.com/v2/zones/a4e29ed3-d7a4-4e4d-945d-ce64678d3b94" - } + "self": "http://dns.provider.com:9001/v2/zones/45fd892d-7a67-4f65-9df0-87273f228d6c" + }, + "transferred_at": null, + "created_at": "2016-03-14T07:50:38.000000", + "pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "updated_at": "2016-03-14T07:50:43.000000", + "version": 2, + "id": "45fd892d-7a67-4f65-9df0-87273f228d6c", + "ttl": 3600, + "action": "NONE", + "attributes": {}, + "serial": 1457941838, + "project_id": "54c3cc0b8e21491f820fc701b83cb7fb", + "type": "PRIMARY", + "email": "hostmaster@example.com", + "description": null }], "links": { - "self": "https://dns.provider.com/v2/zones?name=example.com." - } + "self": "http://dns.provider.com:9001/v2/zones?name=example.com." + }, + "metadata": { + "total_count": 1 + } } - Wildcards can be placed anywhere within the query. The following example demonstrates the use of wildcards on the right side of a query: @@ -347,41 +366,54 @@ Filtering { "zones": [{ "status": "ACTIVE", - "description": null, - "updated_at": "2014-07-08T20:28:31.000000", - "ttl": 86400, - "serial": 1404851315, - "id": "a4e29ed3-d7a4-4e4d-945d-ce64678d3b94", - "name": "example.com.", - "created_at": "2014-07-08T20:28:19.000000", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "version": 1, - "project_id": "noauth-project", - "email": "hostmaster@example.com", + "masters": [], + "name": "example1.org.", "links": { - "self": "http://dns.provider.com/v2/zones/a4e29ed3-d7a4-4e4d-945d-ce64678d3b94" - } + "self": "http://dns.provider.com:9001/v2/zones/bd1b954e-69cd-4a91-99b4-0bcc08533123" + }, + "transferred_at": null, + "created_at": "2016-03-14T05:41:49.000000", + "pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "updated_at": "2016-03-14T07:33:49.000000", + "version": 10, + "id": "bd1b954e-69cd-4a91-99b4-0bcc08533123", + "ttl": 3600, + "action": "NONE", + "attributes": {}, + "serial": 1457940809, + "project_id": "54c3cc0b8e21491f820fc701b83cb7fb", + "type": "PRIMARY", + "email": "hostmaster@example.com", + "description": null }, { "status": "ACTIVE", - "description": null, - "updated_at": null, - "ttl": 3600, - "serial": 1405435142, - "id": "38dbf635-45cb-4873-8300-6c273f0283c7", - "name": "example.org.", - "created_at": "2014-07-15T14:39:02.000000", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "version": 1, - "project_id": "noauth-project", - "email": "hostmaster@example.org", + "masters": [], + "name": "example.com.", "links": { - "self": "http://dns.provider.com/v2/zones/38dbf635-45cb-4873-8300-6c273f0283c7" - } + "self": "http://dns.provider.com:9001/v2/zones/45fd892d-7a67-4f65-9df0-87273f228d6c" + }, + "transferred_at": null, + "created_at": "2016-03-14T07:50:38.000000", + "pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "updated_at": "2016-03-14T07:50:43.000000", + "version": 2, + "id": "45fd892d-7a67-4f65-9df0-87273f228d6c", + "ttl": 3600, + "action": "NONE", + "attributes": {}, + "serial": 1457941838, + "project_id": "54c3cc0b8e21491f820fc701b83cb7fb", + "type": "PRIMARY", + "email": "hostmaster@example.com", + "description": null }], "links": { - "self": "https://dns.provider.com/v2/zones?name=example*" - } + "self": "http://dns.provider.com:9001/v2/zones?name=example%2A" + }, + "metadata": { + "total_count": 2 + } } This example demonstrates the use of multiple wildcards: @@ -405,78 +437,100 @@ Filtering { "zones": [{ "status": "ACTIVE", - "description": null, - "updated_at": "2014-07-08T20:28:31.000000", - "ttl": 86400, - "serial": 1404851315, - "id": "a4e29ed3-d7a4-4e4d-945d-ce64678d3b94", - "name": "example.com.", - "created_at": "2014-07-08T20:28:19.000000", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "version": 1, - "project_id": "noauth-project", - "email": "hostmaster@example.com", - "links": { - "self": "http://dns.provider.com/v2/zones/a4e29ed3-d7a4-4e4d-945d-ce64678d3b94" - } - }, - { - "status": "ACTIVE", - "description": null, - "updated_at": null, - "ttl": 3600, - "serial": 1405435099, - "id": "13db810b-917d-4898-bc28-4d4ee370d20d", - "name": "abc.example.com.", - "created_at": "2014-07-15T14:38:19.000000", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "version": 1, - "project_id": "noauth-project", - "email": "hostmaster@example.com", - "links": { - "self": "http://dns.provider.com/v2/zones/13db810b-917d-4898-bc28-4d4ee370d20d" - } - }, - { - "status": "ACTIVE", - "description": null, - "updated_at": null, - "ttl": 3600, - "serial": 1405435142, - "id": "38dbf635-45cb-4873-8300-6c273f0283c7", + "masters": [], "name": "example.org.", - "created_at": "2014-07-15T14:39:02.000000", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "version": 1, - "project_id": "noauth-project", - "email": "hostmaster@example.org", "links": { - "self": "http://dns.provider.com/v2/zones/38dbf635-45cb-4873-8300-6c273f0283c7" - } + "self": "http://dns.provider.com:9001/v2/zones/c991f02b-ae05-4570-bf75-73def68fe700" + }, + "transferred_at": null, + "created_at": "2016-03-15T05:41:45.000000", + "pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "updated_at": "2016-03-15T05:41:50.000000", + "version": 2, + "id": "c991f02b-ae05-4570-bf75-73def68fe700", + "ttl": 3600, + "action": "NONE", + "attributes": {}, + "serial": 1458020505, + "project_id": "6b89012cdb2640c3a80b8d777d9bac16", + "type": "PRIMARY", + "email": "hostmaster@example.com", + "description": null }, { "status": "ACTIVE", - "description": null, - "updated_at": null, - "ttl": 3600, - "serial": 1405435156, - "id": "c316def0-8599-4030-9dcd-2ce566348115", - "name": "abc.example.net.", - "created_at": "2014-07-15T14:39:16.000000", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "version": 1, - "project_id": "noauth-project", - "email": "hostmaster@example.net", + "masters": [], + "name": "example1.org.", "links": { - "self": "http://dns.provider.com/v2/zones/c316def0-8599-4030-9dcd-2ce566348115" - } + "self": "http://dns.provider.com:9001/v2/zones/0d35ce4e-f3b4-4ba7-9b94-4f9eba49018a" + }, + "transferred_at": null, + "created_at": "2016-03-15T05:54:24.000000", + "pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "updated_at": "2016-03-15T05:54:44.000000", + "version": 2, + "id": "0d35ce4e-f3b4-4ba7-9b94-4f9eba49018a", + "ttl": 3600, + "action": "NONE", + "attributes": {}, + "serial": 1458021264, + "project_id": "6b89012cdb2640c3a80b8d777d9bac16", + "type": "PRIMARY", + "email": "hostmaster@example.com", + "description": null + }, + { + "status": "ACTIVE", + "masters": [], + "name": "example.com.", + "links": { + "self": "http://dns.provider.com:9001/v2/zones/a18eed67-806f-418c-883c-b7a8001a9fb6" + }, + "transferred_at": null, + "created_at": "2016-03-15T06:51:47.000000", + "pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "updated_at": "2016-03-15T06:51:52.000000", + "version": 2, + "id": "a18eed67-806f-418c-883c-b7a8001a9fb6", + "ttl": 3600, + "action": "NONE", + "attributes": {}, + "serial": 1458024707, + "project_id": "6b89012cdb2640c3a80b8d777d9bac16", + "type": "PRIMARY", + "email": "hostmaster@example.com", + "description": null + }, + { + "status": "ACTIVE", + "masters": [], + "name": "abc.example.org.", + "links": { + "self": "http://dns.provider.com:9001/v2/zones/c3cf2487-6c3e-44cd-a305-d52ccb7aaebd" + }, + "transferred_at": null, + "created_at": "2016-03-15T06:53:13.000000", + "pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "updated_at": "2016-03-15T06:53:18.000000", + "version": 2, + "id": "c3cf2487-6c3e-44cd-a305-d52ccb7aaebd", + "ttl": 3600, + "action": "NONE", + "attributes": {}, + "serial": 1458024793, + "project_id": "6b89012cdb2640c3a80b8d777d9bac16", + "type": "PRIMARY", + "email": "hostmaster@example.com", + "description": null }], "links": { - "self": "https://dns.provider.com/v2/zones?name=*example*" - } + "self": "http://dns.provider.com:9001/v2/zones?name=%2Aexample%2A" + }, + "metadata": { + "total_count": 4 + } } - Nested Collections ------------------ @@ -487,4 +541,4 @@ Nested Collections By default, Nested Collections shall not be included in the listing of it's parent resource. For example, List RecordSets shall not include the "records" collection for each of the - RecordSets returned. + RecordSets returned. \ No newline at end of file diff --git a/doc/source/rest/v2/recordsets.rst b/doc/source/rest/v2/recordsets.rst index 5a9e63c41..305e31770 100644 --- a/doc/source/rest/v2/recordsets.rst +++ b/doc/source/rest/v2/recordsets.rst @@ -168,62 +168,70 @@ List Record Sets { "recordsets": [ { + "status": "ACTIVE", "description": null, "links": { - "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/65ee6b49-bb4c-4e52-9799-31330c94161f" + "self": "http://127.0.0.1:9001/v2/zones/c991f02b-ae05-4570-bf75-73def68fe700/recordsets/29c5420e-8acb-4ef9-9aca-709a196c22dc" }, - "updated_at": null, + "created_at": "2016-03-15T05:41:45.000000", + "updated_at": "2016-03-15T07:34:02.000000", "records": [ - "ns2.example.com." + "ns1.example.com. abc.example.com. 1458027242 3586 600 86400 3600" ], + "zone_id": "c991f02b-ae05-4570-bf75-73def68fe700", + "version": 2, "ttl": null, - "id": "65ee6b49-bb4c-4e52-9799-31330c94161f", - "name": "example.org.", - "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f", - "created_at": "2014-10-24T19:59:11.000000", - "version": 1, - "type": "NS" + "action": "NONE", + "type": "SOA", + "id": "29c5420e-8acb-4ef9-9aca-709a196c22dc", + "name": "example.org." }, { - "description": null, - "links": { - "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/14500cf9-bdff-48f6-b06b-5fc7491ffd9e" - }, - "updated_at": "2014-10-24T19:59:46.000000", - "records": [ - "ns2.example.com. joe.example.org. 1414180785 3600 600 86400 3600" - ], - "ttl": null, - "id": "14500cf9-bdff-48f6-b06b-5fc7491ffd9e", - "name": "example.org.", - "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f", - "created_at": "2014-10-24T19:59:12.000000", - "version": 1, - "type": "SOA" + "status": "ACTIVE", + "description": null, + "links": { + "self": "http://127.0.0.1:9001/v2/zones/c991f02b-ae05-4570-bf75-73def68fe700/recordsets/7d80c4c6-e416-41d3-a29b-f408b9f51b8e" + }, + "created_at": "2016-03-15T05:41:45.000000", + "updated_at": null, + "records": [ + "ns1.example.com." + ], + "zone_id": "c991f02b-ae05-4570-bf75-73def68fe700", + "version": 1, + "ttl": null, + "action": "NONE", + "type": "NS", + "id": "7d80c4c6-e416-41d3-a29b-f408b9f51b8e", + "name": "example.org." }, { - "description": "This is an example recordset.", - "links": { - "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648" - }, - "updated_at": null, - "records": [ - "10.1.0.2" - ], - "ttl": 3600, - "id": "f7b10e9b-0cae-4a91-b162-562bc6096648", - "name": "example.org.", - "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f", - "created_at": "2014-10-24T19:59:44.000000", - "version": 1, - "type": "A" + "status": "ACTIVE", + "description": "this is an example recordset", + "links": { + "self": "http://127.0.0.1:9001/v2/zones/c991f02b-ae05-4570-bf75-73def68fe700/recordsets/345e779d-90a4-4245-a460-42721a750e8c" + }, + "created_at": "2016-03-15T07:34:02.000000", + "updated_at": null, + "records": ["10.1.0.2"], + "zone_id": "c991f02b-ae05-4570-bf75-73def68fe700", + "version": 1, + "ttl": null, + "action": "NONE", + "type": "A", + "id": "345e779d-90a4-4245-a460-42721a750e8c", + "name": "example.org." } ], "links": { - "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets" + "self": "http://127.0.0.1:9001/v2/zones/c991f02b-ae05-4570-bf75-73def68fe700/recordsets" + }, + "metadata": { + "total_count": 3 } } + :statuscode 200: Success :statuscode 401: Access Denied diff --git a/doc/source/rest/v2/zones.rst b/doc/source/rest/v2/zones.rst index d1064c763..4574db1d3 100644 --- a/doc/source/rest/v2/zones.rst +++ b/doc/source/rest/v2/zones.rst @@ -199,47 +199,55 @@ List Zones { "zones": [{ - "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66", + "status": "ACTIVE", + "masters": [], "name": "example.org.", - "email": "joe@example.org.", - "ttl": 7200, - "serial": 1404757531, - "status": "ACTIVE", - "description": "This is an example zone.", - "masters": [], - "type": "PRIMARY", - "transferred_at": null, - "version": 1, - "created_at": "2014-07-07T18:25:31.275934", - "updated_at": null, "links": { - "self": "https://127.0.0.1:9001/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3" - } - }, { - "id": "fdd7b0dc-52a3-491e-829f-41d18e1d3ada", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66", - "name": "example.net.", - "email": "joe@example.net.", - "ttl": 7200, - "serial": 1404756682, - "status": "ACTIVE", - "description": "This is another example zone.", - "masters": [], - "type": "PRIMARY", + "self": "http://127.0.0.1:9001/v2/zones/c991f02b-ae05-4570-bf75-73def68fe700" + }, "transferred_at": null, - "version": 1, - "created_at": "2014-07-07T18:22:08.287743", - "updated_at": null, + "created_at": "2016-03-15T05:41:45.000000", + "pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "updated_at": "2016-03-15T05:41:50.000000", + "version": 2, + "id": "c991f02b-ae05-4570-bf75-73def68fe700", + "ttl": 3600, + "action": "NONE", + "attributes": {}, + "serial": 1458020505, + "project_id": "6b89012cdb2640c3a80b8d777d9bac16", + "type": "PRIMARY", + "email": "abc@example.com", + "description": null + }, + { + "status": "ACTIVE", + "masters": [], + "name": "example1.org.", "links": { - "self": "https://127.0.0.1:9001/v2/zones/fdd7b0dc-52a3-491e-829f-41d18e1d3ada" - } + "self": "http://127.0.0.1:9001/v2/zones/0d35ce4e-f3b4-4ba7-9b94-4f9eba49018a" + }, + "transferred_at": null, + "created_at": "2016-03-15T05:54:24.000000", + "pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "updated_at": "2016-03-15T05:54:44.000000", + "version": 2, + "id": "0d35ce4e-f3b4-4ba7-9b94-4f9eba49018a", + "ttl": 3600, + "action": "NONE", + "attributes": {}, + "serial": 1458021264, + "project_id": "6b89012cdb2640c3a80b8d777d9bac16", + "type": "PRIMARY", + "email": "abc@example.com", + "description": null }], "links": { - "self": "https://127.0.0.1:9001/v2/zones" - } + "self": "http://127.0.0.1:9001/v2/zones" + }, + "metadata": { + "total_count": 2 + } } :statuscode 200: Success