From 5c0b0f78b32bd893b1c7e5109ed35eaf59db3eb3 Mon Sep 17 00:00:00 2001 From: Graham Hayes Date: Tue, 14 Jun 2016 14:55:52 +0100 Subject: [PATCH] Move APIv2 Docs to api-ref site Change-Id: Ie9533b6d1bdc44be23d9d91926430aac712f303d --- doc/source/production-guidelines.rst | 5 +- doc/source/rest.rst | 17 +- doc/source/rest/v2/blacklists.rst | 284 ------- doc/source/rest/v2/collections.rst | 544 ------------ doc/source/rest/v2/limits.rst | 67 -- doc/source/rest/v2/pools.rst | 329 -------- doc/source/rest/v2/recordsets.rst | 805 ------------------ doc/source/rest/v2/reverse.rst | 236 ------ doc/source/rest/v2/service_status.rst | 149 ---- doc/source/rest/v2/tlds.rst | 269 ------ doc/source/rest/v2/tsigkeys.rst | 265 ------ doc/source/rest/v2/zones.rst | 1105 ------------------------- 12 files changed, 7 insertions(+), 4068 deletions(-) delete mode 100644 doc/source/rest/v2/blacklists.rst delete mode 100644 doc/source/rest/v2/collections.rst delete mode 100644 doc/source/rest/v2/limits.rst delete mode 100644 doc/source/rest/v2/pools.rst delete mode 100644 doc/source/rest/v2/recordsets.rst delete mode 100644 doc/source/rest/v2/reverse.rst delete mode 100644 doc/source/rest/v2/service_status.rst delete mode 100644 doc/source/rest/v2/tlds.rst delete mode 100644 doc/source/rest/v2/tsigkeys.rst delete mode 100644 doc/source/rest/v2/zones.rst diff --git a/doc/source/production-guidelines.rst b/doc/source/production-guidelines.rst index 797dd58fd..efb94fcff 100644 --- a/doc/source/production-guidelines.rst +++ b/doc/source/production-guidelines.rst @@ -41,7 +41,7 @@ Scenario #3 Mitigation This scenario can be mitigated by ensuring Designate has been configured, and is updated periodically, with the latest list of gTLD's published as the `IANA TLD list`_. These TLDs can be entered into Designate through the -:doc:`TLD API `. +`TLD API`_ Scenario #4 Mitigation ---------------------- @@ -54,7 +54,7 @@ up to fill this gap, crowdsourcing the list of "public suffixes", which includes both standard TLDs and public second level domains. We recommend configuring, and periodically updating, Designate with Mozilla's `Public Suffix list`_. These public suffixes can be entered into Designate -through the :doc:`TLD API `. +through the `TLD API`_ DNS Cache Poisoning =================== @@ -107,3 +107,4 @@ In the main PowerDNS configuration file, include the following statement:: .. _IANA TLD list: https://data.iana.org/TLD/tlds-alpha-by-domain.txt .. _Public Suffix list: https://publicsuffix.org/ .. _Bug 1471159: https://bugs.launchpad.net/designate/+bug/1471159 +.. _TLD API: http://developer.openstack.org/api-ref/dns/#tld diff --git a/doc/source/rest.rst b/doc/source/rest.rst index 95229f8e8..694f01a4f 100644 --- a/doc/source/rest.rst +++ b/doc/source/rest.rst @@ -81,20 +81,9 @@ V1 API V2 API ------ - .. toctree:: - :maxdepth: 2 - :glob: - rest/v2/collections - rest/v2/zones - rest/v2/recordsets - rest/v2/tlds - rest/v2/blacklists - rest/v2/pools - rest/v2/limits - rest/v2/reverse - rest/v2/service_status - rest/v2/tsigkeys + The V2 API is documented on the OpenStack Developer `api site`_ + Admin API --------- @@ -103,3 +92,5 @@ Admin API :glob: rest/admin/quotas + +.. _api site: http://developer.openstack.org/api-ref/dns/ diff --git a/doc/source/rest/v2/blacklists.rst b/doc/source/rest/v2/blacklists.rst deleted file mode 100644 index 6822e62bc..000000000 --- a/doc/source/rest/v2/blacklists.rst +++ /dev/null @@ -1,284 +0,0 @@ -.. - Copyright (c) 2014 Rackspace Hosting - All Rights Reserved. - - Author: Betsy Luzader - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Blacklists -========== - -Overview -------------------- -The blacklist entries are used to manage blacklisted zones. If a zone is blacklisted, then it cannot be used to -create a zone. By default, only an admin can manage these entries. Blacklisted zones are stored as a regular expression -(regex) pattern in the :ref:`database` in the *blacklists* table. - -Blacklist Checks -------------------- -Every time a new zone is created, that domain name is checked against the blacklisted zones in the database. -If it matches the regex pattern, then a 400 is returned with the message "Blacklisted domain name". If there -is no match, then the zone is created. When a new blacklisted pattern is added, it will catch any matching -new zones, but it does not check for existing zones that match the blacklisted pattern. - -Regular Expressions -------------------- -Any valid regular expression may be added to the blacklists table. Here are some examples: - -#. ``^example\\.com\\.$`` - This will block the "example.com." domain, but will not block any sub-domains, e.g. "my.example.com." or anything - else containing example.com, such as, "myexample.com." - -#. ``^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$`` - This will block "example.com." and all sub-domains, e.g. "my.example.com.", but anything else containing - example.com, will not be blocked, such as, "myexample.com." - -*NOTE:* When using regular expressions in json, the '\\' character needs to be escaped with an additional '\\', so it -needs to be written as "^example\\\\.com\\\\.$" - -Create a Blacklist ------------------- - -.. http:post:: /blacklists - - Create a blacklist. *pattern* is the only entry that is required. The domain name part of the pattern - should end in a period (.).' - - **Example request**: - - .. sourcecode:: http - - POST /blacklists HTTP/1.1 - Host: example.com - Accept: application/json - Content-Type: application/json - - { - "pattern" : "^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$", - "description" : "This is a blacklisted domain." - } - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 201 Created - Content-Type: application/json; charset=UTF-8 - Location: 127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd - - { - "description":"This is a blacklisted domain.", - "links":{ - "self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd" - }, - "pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$", - "created_at":"2014-03-11T21:54:57.000000", - "updated_at":null, - "id":"c47229fb-0831-4b55-a5b5-380d361be4bd" - } - - :form created_at: timestamp - :form updated_at: timestamp - :form pattern: blacklist regular expression - :form id: uuid - :form description: UTF-8 text field - :form links: links to traverse the list - :statuscode 201: Created - :statuscode 401: Access Denied - :statuscode 400: Invalid Object - :statuscode 409: Duplicate Blacklist - -Get a Blacklist ---------------- - -.. http:get:: /blacklists/(uuid:id) - - Lists a particular Blacklisted domain - - **Example request**: - - .. sourcecode:: http - - GET /blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1 - Host: example.com - Accept: application/json - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json; charset=UTF-8 - - { - "description":"This is a blacklisted domain.", - "links":{ - "self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd" - }, - "pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$", - "created_at":"2014-03-11T21:54:57.000000", - "updated_at":null, - "id":"c47229fb-0831-4b55-a5b5-380d361be4bd" - } - - :form created_at: timestamp - :form updated_at: timestamp - :form pattern: blacklist regular expression - :form id: uuid - :form description: UTF-8 text field - :form links: links to traverse the list - :statuscode 200: OK - :statuscode 401: Access Denied - :statuscode 404: Blacklist not found - -List Blacklists ---------------- - -.. http:get:: /blacklists - - Lists all blacklists - - **Example request**: - - .. sourcecode:: http - - GET /blacklists HTTP/1.1 - Host: example.com - Accept: application/json - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json; charset=UTF-8 - - { - "blacklists":[ - { - "description": "This is a blacklisted domain.", - "links":{ - "self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd" - }, - "pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$", - "created_at":"2014-03-11T21:54:57.000000", - "updated_at":null, - "id":"c47229fb-0831-4b55-a5b5-380d361be4bd" - }, - { - "description": null, - "links":{ - "self":"http://127.0.0.1:9001/v2/blacklists/61140aff-e2c8-488b-9bf4-da710ec8732b" - }, - "pattern" : "^examples\\.com\\.$", - "created_at":"2014-03-07T21:05:59.000000", - "updated_at":null, - "id":"61140aff-e2c8-488b-9bf4-da710ec8732b" - } - ], - "links":{ - "self":"http://127.0.0.1:9001/v2/blacklists" - } - } - - :form created_at: timestamp - :form updated_at: timestamp - :form pattern: blacklist regular expression - :form id: uuid - :form description: UTF-8 text field - :form links: links to traverse the list - :statuscode 200: OK - :statuscode 401: Access Denied - -Update a Blacklist ------------------- - -.. http:patch:: /blacklists/(uuid:id) - - updates a blacklist - - **Example request**: - - .. sourcecode:: http - - PATCH blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1 - Host: example.com - Accept: application/json - Content-Type: application/json - - { - "pattern" : "^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$", - "description" : "Updated the description" - } - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json; charset=UTF-8 - - { - "description":"Updated the pattern to catch subdomains", - "links":{ - "self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd" - }, - "created_at":"2014-03-11T21:54:57.000000", - "updated_at":"2014-03-13T16:49:32.117187", - "id":"c47229fb-0831-4b55-a5b5-380d361be4bd", - "pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$" - } - - :form created_at: timestamp - :form updated_at: timestamp - :form pattern: blacklist regular expression pattern - :form id: uuid - :form description: UTF-8 text field - :form links: links to traverse the list - :statuscode 200: OK - :statuscode 401: Access Denied - :statuscode 404: Blacklist not found - :statuscode 409: Duplicate Blacklist - -Delete a Blacklist ------------------- - -.. http:delete:: /blacklists/(uuid:id) - - delete a blacklist - - **Example request**: - - .. sourcecode:: http - - DELETE /blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1 - Host: example.com - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 204 No Content - Content-Type: application/json; charset=UTF-8 - Content-Length: 0 - - :statuscode 204: No Content - :statuscode 401: Access Denied - :statuscode 404: Blacklist not found - - - - - - diff --git a/doc/source/rest/v2/collections.rst b/doc/source/rest/v2/collections.rst deleted file mode 100644 index 215625f6b..000000000 --- a/doc/source/rest/v2/collections.rst +++ /dev/null @@ -1,544 +0,0 @@ -.. - Copyright 2014 Rackspace Hosting - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -.. - -Collections -=========== - -The following conventions apply to all collections, unless otherwise noted below. - -Links ------ - - A links object will exist at the root of all Collection responses. - At the minimum, it will contain a "self" link. If the collection - resultset is not complete, a "next" link will be included for - pagination. - - **Request:** - - .. sourcecode:: http - - GET /v2/zones?limit=2 HTTP/1.1 - Host: dns.provider.com - Accept: application/json - - **Response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "zones": [{ - "status": "ACTIVE", - "masters": [], - "name": "example1.org.", - "links": { - "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", - "masters": [], - "name": "example.com.", - "links": { - "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 ----------------------- - - Pagination is available on all collections and is controlled - using a combination of four optional query parameters: - - * `marker` - denotes the ID of the last item in the previous list. - * `limit` - use to set the maximum number of items per page, use - "max" to return the upper limit of results as defined - by the operator. If not supplied, the default per page - limit as defined by the operator will be used. - * `sort_key` - sorts the results by the specified attribute - - * By default, elements will be sorted by their creation date. - - * `sort_dir` - determines whether sorted results are displayed in - ascending or descending order. - - * If explicitly used, the value of sort_dir must be either - 'asc' or 'desc'. Otherwise, the default is 'asc'. - - To navigate the collection, the parameters limit and marker can be - set in the URI (e.g.?limit=100&marker=). Items are sorted, as - a default, by create time in ascending order. - - - - Collection responses will include a `links` object containing absolute - URLs for the current and next page. These links may be omitted, or - null, at the edges of a paginated collection. - - The following example takes a collection of zones and sorts it in - descending order, using ID as the sort key rather than creation date. - - **Request:** - - .. sourcecode:: http - - GET /v2/zones?sort_key=id&sort_dir=desc HTTP/1.1 - Host: dns.provider.com - Accept: application/json - - **Response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "zones": [{ - "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", - "links": { - "self": "http://dns.provider.com/v2/zones/c316def0-8599-4030-9dcd-2ce566348115" - } - }, - { - "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": 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", - "links": { - "self": "http://dns.provider.com/v2/zones/38dbf635-45cb-4873-8300-6c273f0283c7" - } - }, - { - "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" - } - }], - "links": { - "self": "https://dns.provider.com/v2/zones?sort_key=id&sort_dir=desc" - } - } - - - This example takes the previously sorted list and displays only the middle two resources. - - .. sourcecode:: http - - GET /v2/zones?sort_key=id&sort_dir=desc&marker=c316def0-8599-4030-9dcd-2ce566348115&limit=2 HTTP/1.1 - Host: dns.provider.com - Accept: application/json - - **Response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "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": 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", - "links": { - "self": "http://dns.provider.com/v2/zones/38dbf635-45cb-4873-8300-6c273f0283c7" - } - }], - "links": { - "self": "https://dns.provider.com/v2/zones?sort_key=id&sort_dir=desc&marker=c316def0-8599-4030-9dcd-2ce566348115&limit=2", - "next": "https://dns.provider.com/v2/zones?sort_key=id&sort_dir=desc&limit=2&marker=38dbf635-45cb-4873-8300-6c273f0283c7" - } - } - -Filtering ---------- - - Filtering is available on all collections and is controlled using - query parameters which match the name of the attribute being filtered. - It is *not* required that all attributes are available as filter - targets, but the majority will be. - - Currently, the following attributes support filtering: - - * **Blacklists**: pattern - * **Recordsets**: name, type, ttl, data, description, status - * **TLDs**: name - * **Zones**: name, email, ttl, description, status - - Filters can be an exact match search or a wildcard search. Currently, - wildcard search is supported using the '*' character. - - The following example takes a collection of zones and filters it - by the "name" parameter. - - **Request:** - - .. sourcecode:: http - - GET /v2/zones?name=example.com. HTTP/1.1 - Host: dns.provider.com - Accept: application/json - - - **Response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "zones": [{ - "status": "ACTIVE", - "masters": [], - "name": "example.com.", - "links": { - "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?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: - - **Request:** - - .. sourcecode:: http - - GET /v2/zones?name=example* HTTP/1.1 - Host: dns.provider.com - Accept: application/json - - - **Response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "zones": [{ - "status": "ACTIVE", - "masters": [], - "name": "example1.org.", - "links": { - "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", - "masters": [], - "name": "example.com.", - "links": { - "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?name=example%2A" - }, - "metadata": { - "total_count": 2 - } - } - - This example demonstrates the use of multiple wildcards: - - **Request:** - - .. sourcecode:: http - - GET /v2/zones?name=*example* HTTP/1.1 - Host: dns.provider.com - Accept: application/json - - - **Response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "zones": [{ - "status": "ACTIVE", - "masters": [], - "name": "example.org.", - "links": { - "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", - "masters": [], - "name": "example1.org.", - "links": { - "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": "http://dns.provider.com:9001/v2/zones?name=%2Aexample%2A" - }, - "metadata": { - "total_count": 4 - } - } - -Nested Collections ------------------- - - A nested collection is a collection without a URI of it's own. - The only current example we have of this is the "records" array - under the RecordSet resource. - - 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. \ No newline at end of file diff --git a/doc/source/rest/v2/limits.rst b/doc/source/rest/v2/limits.rst deleted file mode 100644 index 13438f7d3..000000000 --- a/doc/source/rest/v2/limits.rst +++ /dev/null @@ -1,67 +0,0 @@ -.. - Copyright 2015 Hewlett-Packard Development Company, L.P. - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Limits -====== - -Overview -------------------- -This endpoint is used to retrieve current limits. - - -Get Limits ----------- - -.. http:get:: /limits - - Lists current limits - - **Example request**: - - .. sourcecode:: http - - GET /limits HTTP/1.1 - Host: example.com - Accept: application/json - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json; charset=UTF-8 - - { - "max_page_limit": 1000, - "max_recordset_name_length": 255, - "max_recordset_records": 20, - "max_zone_name_length": 255, - "max_zone_records": 500, - "max_zone_recordsets": 500, - "max_zones": 10, - "min_ttl": null - } - - - :form max_page_limit: Max limit for paging - :form max_recordset_name_length: Max length for a RecordSet name - :form max_recordset_records: Max number RecordSet of Records - :form max_zone_name_length: Max length for a Zone name - :form max_zone_records: Max number of Records in a Zone - :form max_zone_recordsets: Max number of RecordSets in a Zone - :form max_zones: Max number of Zones - :form max_ttl: Max TTL - :statuscode 200: OK diff --git a/doc/source/rest/v2/pools.rst b/doc/source/rest/v2/pools.rst deleted file mode 100644 index 6e0d430f0..000000000 --- a/doc/source/rest/v2/pools.rst +++ /dev/null @@ -1,329 +0,0 @@ -.. - Copyright (C) 2015 Rackspace - - Author: Eric Larson - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - - -======= - Pools -======= - -Pools are collection of backend DNS servers such as bind9. The backend -servers in a pool are responsible for answering DNS queries. - -.. note:: - - Currently there is a default pool that is created. Please be aware, - this will change in the future. - - -Create Pool -=========== - -.. http:post:: /pools - - Create a new Pool. - - **Example request**: - - .. code-block:: http - - POST /pools HTTP/1.1 - Host: example.com - Accept: application/json - Content-Type: application/json - - { - "name": "Example Pool", - "ns_records": [ - { - "hostname": "ns1.example.org.", - "priority": 1 - } - ] - } - - - **Example response**: - - .. code-block:: http - - HTTP/1.1 201 Created - Location: http://127.0.0.1:9001/v2/pools/d1716333-8c16-490f-85ee-29af36907605 - Content-Type: application/json; charset=UTF-8 - - { - "description": null, - "id": "d1716333-8c16-490f-85ee-29af36907605", - "project_id": "noauth-project", - "created_at": "2015-02-23T21:56:33.000000", - "attributes": null, - "ns_records": [ - { - "hostname": "ns1.example.org.", - "priority": 1 - } - ], - "links": { - "self": "http://127.0.0.1:9001/v2/pools/d1716333-8c16-490f-85ee-29af36907605" - }, - "name": "example_pool", - "updated_at": null - } - - :form name: UTF-8 text field - :form description: a description of the pool - :form tenant_id: the UUID of the tenant - :form provisioner: the type backend that should be used - :form attributes: meta data for the pool - :form ns_records: a list of ns_records as fully qualified domains - - :statuscode 201: Created - :statuscode 400: Bad Request - :statuscode 401: Access Denied - - -Get Pools -========= - -.. http:get:: /pools - - Get the list of Pools. This resource supports the - :doc:`collections` API. - - **Example request**: - - .. code-block:: http - - GET /pools HTTP/1.1 - Host: example.com - Accept: application/json - - - **Example response**: - - .. code-block:: http - - HTTP/1.1 200 OK - Content-Length: 755 - Content-Type: application/json; charset=UTF-8 - - { - "metadata": null, - "links": { - "self": "http://127.0.0.1:9001/v2/pools" - }, - "pools": [ - { - "description": null, - "id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", - "project_id": null, - "created_at": "2015-02-18T22:18:58.000000", - "attributes": null, - "ns_records": [ - { - "hostname": "ns1.example.org.", - "priority": 1 - } - ], - "links": { - "self": "http://127.0.0.1:9001/v2/pools/794ccc2c-d751-44fe-b57f-8894c9f5c842" - }, - "name": "default", - "updated_at": "2015-02-19T15:59:44.000000" - }, - { - "description": null, - "id": "d1716333-8c16-490f-85ee-29af36907605", - "project_id": "noauth-project", - "created_at": "2015-02-23T21:56:33.000000", - "attributes": null, - "ns_records": [ - { - "hostname": "ns2.example.org.", - "priority": 1 - } - ], - "links": { - "self": "http://127.0.0.1:9001/v2/pools/d1716333-8c16-490f-85ee-29af36907605" - }, - "name": "example_pool", - "updated_at": null - } - ] - } - - :statuscode 200: OK - :statuscode 400: Bad Request - - -Get Pool -======== - -.. http:get:: /pools/(uuid:id) - - Get a specific Pool using the Pool's uuid id. - - **Example request**: - - .. code-block:: http - - GET /pools/d1716333-8c16-490f-85ee-29af36907605 HTTP/1.1 - Host: example.com - Accept: application/json - - **Example response**: - - .. code-block:: http - - HTTP/1.1 200 OK - Content-Length: 349 - Content-Type: application/json; charset=UTF-8 - - { - "description": null, - "id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", - "project_id": null, - "created_at": "2015-02-18T22:18:58.000000", - "attributes": null, - "ns_records": [ - { - "hostname": "ns1.example.org.", - "priority": 1 - } - ], - "links": { - "self": "http://127.0.0.1:9001/v2/pools/794ccc2c-d751-44fe-b57f-8894c9f5c842" - }, - "name": "default", - "updated_at": "2015-02-19T15:59:44.000000" - } - - :statuscode 200: OK - :statuscode 400: Bad Request - - - -Update Pool -=========== - -.. http:patch:: /pools/(uuid:id) - - Update a Pool. - - **Example request**: - - .. code-block:: http - - PATCH /pools/794ccc2c-d751-44fe-b57f-8894c9f5c842 HTTP/1.1 - Host: example.com - Accept: application/json - Content-Type: application/json - - { - "ns_records": [ - { - "hostname": "ns1.example.org.", - "priority": 1 - }, - { - "hostname": "ns3.example.org.", - "priority": 2 - } - ], - } - - **Example response**: - - .. code-block:: http - - HTTP/1.1 200 OK - Content-Length: 369 - Content-Type: application/json; charset=UTF-8 - - { - "description": null, - "id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", - "project_id": null, - "created_at": "2015-02-18T22:18:58.000000", - "attributes": null, - "ns_records": [ - { - "hostname": "ns1.example.org.", - "priority": 1 - } - { - "hostname": "ns3.example.org.", - "priority": 2 - } - ], - "links": { - "self": "http://127.0.0.1:9001/v2/pools/794ccc2c-d751-44fe-b57f-8894c9f5c842" - }, - "name": "default", - "updated_at": "2015-02-24T17:39:07.000000" - } - - .. note:: - - When updating the Pool definition document, take care to ensure - that any existing values are included when updating a field. For - example, if we used - - .. code-block:: json - - { - "ns_records": [ - { - "hostname": "ns3.example.org.", - "priority": 2 - } - ] - } - - This would **replace** the value of the `ns_records` key. - - It is a good practice to perform a GET and mutate the result - accordingly. - - :statuscode 202: Accepted - :statuscode 400: Bad Request - :statuscode 409: Conflict - - -Remove Pool -=========== - -.. http:delete:: /pools/(uuid:id) - - Remove a Pool. When deleting a Pool, the Pool cannot contain any - zones. - - **Example request**: - - .. code-block:: http - - DELETE /pools HTTP/1.1 - Accept: application/json - - **Example response**: - - .. code-block:: http - - HTTP/1.1 204 No Content - Content-Length: 0 - - :statuscode 400: Bad Request - :statuscode 204: Successfully Deleted diff --git a/doc/source/rest/v2/recordsets.rst b/doc/source/rest/v2/recordsets.rst deleted file mode 100644 index e0ad4ea79..000000000 --- a/doc/source/rest/v2/recordsets.rst +++ /dev/null @@ -1,805 +0,0 @@ -.. - Copyright (C) 2014 Rackspace - - Author: Joe McBride - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Record Sets and Records -======================= - -A record set groups together a list of related records. It is the essential content of your zone file and is used to define the various domain to server routes for your application. Record sets are also referred to as "Resource Record Sets" or "RRSet". - -The following illustrates a record set in the BIND file format: - -.. sourcecode:: none - - example.org. 86400 MX 10 mail1.example.org. - 20 mail2.example.org. - 30 mail3.example.org. - -.. note:: The "description" field on Records cannot be accessed from the V2 - API. Likewise, the "description" field on Record Sets cannot be accessed - from the V1 API. - -Create Record Set (A, AAAA, CNAME, NS, and TXT) ------------------------------------------------ - -The following format can be used for common record set types including A, AAAA, CNAME, NS and TXT. Simply replace the type and records with the respective values. NS record sets can only be created and deleted. Examples for MX, SSHFP, SPF and SRV will follow. - -.. http:post:: /zones/(uuid:id)/recordsets - - Creates a new record set. - - **Example request:** - - .. sourcecode:: http - - POST /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - { - "name" : "example.org.", - "description" : "This is an example record set.", - "type" : "A", - "ttl" : 3600, - "records" : [ - "10.1.0.2" - ] - } - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "description": "This is an example record set.", - "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" - } - - - :form description: UTF-8 text field - :form name: domain name - :form ttl: time-to-live numeric value in seconds - :form type: type of record set - :form records: a list of record values - - :statuscode 201: Created - :statuscode 202: Accepted - :statuscode 401: Access Denied - -Get Record Set --------------- - -Two APIs can be used to retrieve a single recordset. One with zone ID in url, the other without. - -.. http:get:: /zones/(uuid:id)/recordsets/(uuid:id) - - Retrieves a record set with the specified record set ID. - - **Example request:** - - .. sourcecode:: http - - GET /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648 HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Vary: Accept - Content-Type: application/json - - { - "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" - } - - :statuscode 200: Success - :statuscode 401: Access Denied - -.. http:get:: /recordsets/(uuid:id) - - If http client follows redirect, API returns a 200. Otherwise it returns 301 with the canonical location of the requested recordset. - - **Example request:** - - .. sourcecode:: http - - GET /v2/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648 HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Vary: Accept - Content-Type: application/json - - { - "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" - } - - :statuscode 301: Moved Permanently - :statuscode 200: Success - :statuscode 401: Access Denied - -List Record Sets ----------------- - -**Lists all record sets for a given zone** - -.. http:get:: /zones/(uuid:id)/recordsets - - **Example Request:** - - .. sourcecode:: http - - GET /v2/zones/c991f02b-ae05-4570-bf75-73def68fe700/recordsets HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - - **Example Response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Vary: Accept - Content-Type: application/json - - { - "recordsets": [ - { - "status": "ACTIVE", - "description": null, - "links": { - "self": "http://127.0.0.1:9001/v2/zones/c991f02b-ae05-4570-bf75-73def68fe700/recordsets/29c5420e-8acb-4ef9-9aca-709a196c22dc" - }, - "created_at": "2016-03-15T05:41:45.000000", - "updated_at": "2016-03-15T07:34:02.000000", - "records": [ - "ns1.example.com. abc.example.com. 1458027242 3586 600 86400 3600" - ], - "zone_id": "c991f02b-ae05-4570-bf75-73def68fe700", - "version": 2, - "ttl": null, - "action": "NONE", - "type": "SOA", - "id": "29c5420e-8acb-4ef9-9aca-709a196c22dc", - "name": "example.org." - }, - { - "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." - }, - { - "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": "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 - -**Lists record sets across all zones** - -.. http:get:: /recordsets - - **Example Request:** - - .. sourcecode:: http - - GET /v2/recordsets HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - - **Example Response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Vary: Accept - Content-Type: application/json - - { - "recordsets": [ - { - "description": null, - "links": { - "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/65ee6b49-bb4c-4e52-9799-31330c94161f" - }, - "updated_at": null, - "records": [ - "ns1.devstack.org." - ], - "action": "NONE", - "ttl": null, - "status": "ACTIVE", - "id": "65ee6b49-bb4c-4e52-9799-31330c94161f", - "name": "example.org.", - "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f", - "zone_name": "example.org.", - "created_at": "2014-10-24T19:59:11.000000", - "version": 1, - "type": "NS" - }, - { - "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": [ - "ns1.devstack.org. jli.ex.com. 1458666091 3502 600 86400 3600" - ], - "action": "NONE", - "ttl": null, - "status": "ACTIVE", - "id": "14500cf9-bdff-48f6-b06b-5fc7491ffd9e", - "name": "example.org.", - "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f", - "zone_name": "example.org.", - "created_at": "2014-10-24T19:59:12.000000", - "version": 1, - "type": "SOA" - }, - { - "name": "example.com.", - "id": "12caacfd-f0fc-4bcb-aa24-c42769897822", - "type": "SOA", - "zone_name": "example.com.", - "action": "NONE", - "ttl": null, - "status": "ACTIVE", - "description": null, - "links": { - "self": "http://127.0.0.1:9001/v2/zones/b8d7eaf1-e5c7-4b15-be6e-4b2809f47ec3/recordsets/12caacfd-f0fc-4bcb-aa24-c42769897822" - }, - "created_at": "2016-03-22T16:12:35.000000", - "updated_at": "2016-03-22T17:01:31.000000", - "records": [ - "ns1.devstack.org. jli.ex.com. 1458666091 3502 600 86400 3600" - ], - "zone_id": "b8d7eaf1-e5c7-4b15-be6e-4b2809f47ec3", - "version": 2 - }, - { - "name": "example.com.", - "id": "f39c51d1-ec2c-48a8-b9f7-877d56b7b82a", - "type": "NS", - "zone_name": "example.com.", - "action": "NONE", - "ttl": null, - "status": "ACTIVE", - "description": null, - "links": { - "self": "http://127.0.0.1:9001/v2/zones/b8d7eaf1-e5c7-4b15-be6e-4b2809f47ec3/recordsets/f39c51d1-ec2c-48a8-b9f7-877d56b7b82a" - }, - "created_at": "2016-03-22T16:12:35.000000", - "updated_at": null, - "records": [ - "ns1.devstack.org." - ], - "zone_id": "b8d7eaf1-e5c7-4b15-be6e-4b2809f47ec3", - "version": 1 - }, - ], - "metadata": { - "total_count": 4 - }, - "links": { - "self": "https://127.0.0.1:9001/v2/recordsets" - } - } - -**Filtering record sets** - -.. http:get:: /recordsets?KEY=VALUE - - **Example Request:** - - .. sourcecode:: http - - GET /v2/recordsets?data=192.168* HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - - **Example Response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Vary: Accept - Content-Type: application/json - - { - "metadata": { - "total_count": 2 - }, - "links": { - "self": "http://127.0.0.1:9001/v2/recordsets?data=192.168%2A" - }, - "recordsets": [ - { - "name": "mail.example.net.", - "id": "a48588c5-5093-4585-b0fc-3e399d169c01", - "type": "A", - "zone_name": "example.net.", - "action": "NONE", - "ttl": null, - "status": "ACTIVE", - "description": null, - "links": { - "self": "http://127.0.0.1:9001/v2/zones/601a25f0-5c4d-4058-8d9c-e6a78f5ffbb8/recordsets/a48588c5-5093-4585-b0fc-3e399d169c01" - }, - "created_at": "2016-04-04T20:11:08.000000", - "updated_at": null, - "records": [ - "192.168.0.1" - ], - "zone_id": "601a25f0-5c4d-4058-8d9c-e6a78f5ffbb8", - "version": 1 - }, - { - "name": "www.example.net.", - "id": "f2c7a0f6-8ec7-4d14-b8ec-2a55a8129160", - "type": "A", - "zone_name": "example.net.", - "action": "NONE", - "ttl": null, - "status": "ACTIVE", - "description": null, - "links": { - "self": "http://127.0.0.1:9001/v2/zones/601a25f0-5c4d-4058-8d9c-e6a78f5ffbb8/recordsets/f2c7a0f6-8ec7-4d14-b8ec-2a55a8129160" - }, - "created_at": "2016-04-04T22:21:03.000000", - "updated_at": null, - "records": [ - "192.168.6.6" - ], - "zone_id": "601a25f0-5c4d-4058-8d9c-e6a78f5ffbb8", - "version": 1 - } - ] - } - -Update Record Set ------------------ - -.. http:put:: /zones/(uuid:id)/recordsets/(uuid:id) - - Replaces the record set with the specified details. - - In the example below, we update the TTL to 3600. - - **Request:** - - .. sourcecode:: http - - PUT /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648 HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - { - "description" : "I updated this example.", - "ttl" : 60, - "records" : [ - "10.1.0.2" - ] - } - - **Response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "description": "I updated this example.", - "ttl": 60, - "records": [ - "10.1.0.2" - ], - "links": { - "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648" - }, - "updated_at": "2014-10-24T20:15:27.000000", - "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": 2, - "type": "A" - } - - :form description: UTF-8 text field - :form name: domain name - :form ttl: time-to-live numeric value in seconds - :form type: type of record set (can not be changed on update) - :form records: a list of data records - - :statuscode 200: Success - :statuscode 202: Accepted - :statuscode 401: Access Denied - -Delete Record Set ------------------ - -.. http:delete:: zones/(uuid:id)/recordsets/(uuid:id) - - Deletes a record set with the specified record set ID. - - **Example Request:** - - .. sourcecode:: http - - DELETE /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648 HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - **Example Response:** - - .. sourcecode:: http - - HTTP/1.1 202 Accepted - - :statuscode: 202 Accepted - -Create MX Record Set --------------------- - -.. http:post:: /zones/(uuid:id)/recordsets - - Creates a new MX record set. MX record set data format is " " (e.g. "10 10.1.0.1"). - - **Example request:** - - .. sourcecode:: http - - POST /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - { - "name" : "mail.example.org.", - "description" : "An MX recordset.", - "type" : "MX", - "ttl" : 3600, - "records" : [ - "10 mail1.example.org.", - "20 mail2.example.org.", - "30 mail3.example.org.", - "40 mail4.example.org." - ] - } - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "description": "An MX recordset.", - "links": { - "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096649" - }, - "updated_at": null, - "records" : [ - "10 mail1.example.org.", - "20 mail2.example.org.", - "30 mail3.example.org.", - "40 mail4.example.org." - ], - "ttl": 3600, - "id": "f7b10e9b-0cae-4a91-b162-562bc6096649", - "name": "mail.example.org.", - "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f", - "created_at": "2014-10-25T19:59:44.000000", - "version": 1, - "type": "MX" - } - - - :form description: UTF-8 text field - :form name: domain name - :form ttl: time-to-live numeric value in seconds - :form type: type of record set - :form records: a list of record values - - :statuscode 201: Created - :statuscode 401: Access Denied - -Create SSHFP Record Set ------------------------ - -.. http:post:: /zones/(uuid:id)/recordsets - - Creates a new SSHFP record set. SSHFP record set data format is " " (e.g. "1 2 aa2df857dc65c5359f02ca75ec5c4308c0100594d931e8d243a42f586257b5e8"). - - **Example request:** - - .. sourcecode:: http - - POST /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - { - "name" : "foo.example.org.", - "description" : "An SSHFP recordset.", - "type" : "SSHFP", - "ttl" : 3600, - "records" : [ - "1 2 aa2df857dc65c5359f02ca75ec5c4308c0100594d931e8d243a42f586257b5e8" - ] - } - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "description": "An SSHFP recordset.", - "links": { - "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096650" - }, - "updated_at": null, - "records" : [ - "1 2 aa2df857dc65c5359f02ca75ec5c4308c0100594d931e8d243a42f586257b5e8" - ], - "ttl": 3600, - "id": "f7b10e9b-0cae-4a91-b162-562bc6096650", - "name": "foo.example.org.", - "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f", - "created_at": "2014-11-10T19:59:44.000000", - "version": 1, - "type": "SSHFP" - } - - - :form description: UTF-8 text field - :form name: domain name - :form ttl: time-to-live numeric value in seconds - :form type: type of record set - :form records: a list of record values - - :statuscode 201: Created - :statuscode 401: Access Denied - -Create SPF Record Set ---------------------- - -.. http:post:: /zones/(uuid:id)/recordsets - - Creates a new SPF record set. SPF record set data formatting follows standard SPF record syntax. - - **Example request:** - - .. sourcecode:: http - - POST /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - { - "name" : "foospf.example.org.", - "description" : "An SPF recordset.", - "type" : "SPF", - "ttl" : 3600, - "records" : [ - "v=spf1 +all" - ] - } - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "description": "An SPF recordset.", - "links": { - "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096651" - }, - "updated_at": null, - "records" : [ - "v=spf1 +all" - ], - "ttl": 3600, - "id": "f7b10e9b-0cae-4a91-b162-562bc6096651", - "name": "foospf.example.org.", - "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f", - "created_at": "2014-11-10T19:59:44.000000", - "version": 1, - "type": "SPF" - } - - - :form description: UTF-8 text field - :form name: domain name - :form ttl: time-to-live numeric value in seconds - :form type: type of record set - :form records: a list of record values - - :statuscode 201: Created - :statuscode 401: Access Denied - -Create SRV Record Set ---------------------- - -.. http:post:: /zones/(uuid:id)/recordsets - - Creates a new SRV record set. SRV record set data format is " " (e.g. "10 0 5060 server1.example.org."). The "name" attribute should contain the service name, protocol and domain name (e.g. "_sip.tcp.example.org."). - - **Example request:** - - .. sourcecode:: http - - POST /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - { - "name" : "_sip.tcp.example.org.", - "description" : "An SRV recordset.", - "type" : "SRV", - "ttl" : 3600, - "records" : [ - "10 0 5060 server1.example.org." - ] - } - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "description": "An SRV recordset.", - "links": { - "self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096652" - }, - "updated_at": null, - "records" : [ - "10 0 5060 server1.example.org." - ], - "ttl": 3600, - "id": "f7b10e9b-0cae-4a91-b162-562bc6096652", - "name": "_sip.tcp.example.org.", - "zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f", - "created_at": "2014-11-10T19:59:44.000000", - "version": 1, - "type": "SRV" - } - - - :form description: UTF-8 text field - :form name: domain name - :form ttl: time-to-live numeric value in seconds - :form type: type of record set - :form records: a list of record values - - :statuscode 201: Created - :statuscode 401: Access Denied diff --git a/doc/source/rest/v2/reverse.rst b/doc/source/rest/v2/reverse.rst deleted file mode 100644 index 39d786919..000000000 --- a/doc/source/rest/v2/reverse.rst +++ /dev/null @@ -1,236 +0,0 @@ -.. - Copyright 2015 Hewlett-Packard Development Company, L.P. - All Rights Reserved. - - Author: Endre Karlson - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -.. note: - - Currently the /reverse endpoint is used to tie reverse DNS records to IPs. - -FloatingIPs -=========== - -In order to use the FloatingIPs functionality you will need to have a FloatingIP -associated to your project in Neutron. - -Set FloatingIP's PTR record ----------------------------- - -.. http:patch:: /reverse/floatingips/(string:region):(uuid:floatingip_id) - - Set a PTR record for the given FloatingIP. The domain if it does not exist - will be provisioned automatically. - - **Example request**: - - .. sourcecode:: http - - POST /reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1 - Host: example.com - Accept: application/json - Content-Type: application/json - - { - "ptrdname" : "smtp.example.com.", - "description" : "This is a floating ip for 10.0.0.1", - "ttl": 600 - } - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 202 Created - Content-Type: application/json; charset=UTF-8 - Location: http://example.com:9001/v2/reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd - - { - "ptrdname": "smtp.example.com.", - "ttl": 600, - "description":"This is a floating ip for 172.24.4.3", - "address": "172.24.4.3", - "action": "CREATE", - "status": "PENDING", - "links":{ - "self":"http://example.com:9001/v2/reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd" - }, - "pattern":"smtp.example.com.", - "created_at":"2014-03-11T21:54:57.000000", - "updated_at":null, - "id":"RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd", - } - - :form created_at: timestamp - :form updated_at: timestamp - :form ptrdname: Hostname - :form ttl: Time to live - :form address: The FloatingIP address - :form id: A combination of the Region and FloatingIP ID - :form description: UTF-8 text field - :form links: links to traverse the list - :form action: Provisioning Action - :form status: Provisioning Status - :statuscode 202: Created - :statuscode 401: Access Denied - :statuscode 400: Invalid Object - :statuscode 404: FloatingIP / PTR Not found - - -Get a FloatingIP's PTR record ------------------------------ - -.. http:get:: /reverse/floatingips/(string:region):(uuid:floatingip_id) - - Shows a particular FloatingIP PTR - - **Example request**: - - .. sourcecode:: http - - GET /reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1 - Host: example.com - Accept: application/json - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json; charset=UTF-8 - - { - "ptrdname": "smtp.example.com.", - "ttl": 600, - "description":"This is a floating ip for 172.24.4.3", - "address": "172.24.4.3", - "action": "NONE", - "status": "ACTIVE", - "links":{ - "self":"http://example.com:9001/v2/reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd" - }, - "pattern":"smtp.example.com.", - "created_at":"2014-03-11T21:54:57.000000", - "updated_at":null, - "id":"RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd", - } - - :form created_at: timestamp - :form updated_at: timestamp - :form ptrdname: Hostname - :form ttl: Time to live - :form address: The FloatingIP address - :form id: A combination of the Region and FloatingIP ID - :form description: UTF-8 text field - :form links: links to traverse the list - :form action: Provisioning Action - :form status: Provisioning Status - :statuscode 200: OK - :statuscode 404: FloatingIP or PTR not found not found - -List FloatingIP PTR records ---------------------------- - -.. http:get:: /reverse/floatingips/ - - Lists all FloatingIPs PTR records - - **Example request**: - - .. sourcecode:: http - - GET /reverse/floatingips/ HTTP/1.1 - Host: example.com - Accept: application/json - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json; charset=UTF-8 - - { - "floatingips":[ - { - "ttl": 600, - "ptrdname": "smtp.example.com.", - "description":"This is a floating ip for 172.24.4.3", - "address": "172.24.4.3", - "action": "NONE", - "status": "ACTIVE", - "links":{ - "self":"http://example.com:9001/v2/reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd" - }, - "pattern":"smtp.example.com.", - "created_at":"2014-03-11T21:54:57.000000", - "updated_at":null, - "id":"RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd", - }, - { - "ptrdname": "www.example.com.", - "ttl": 600, - "description":"This is a floating ip for 172.24.4.4", - "address": "172.24.4.4", - "action": "NONE", - "status": "ACTIVE", - "links":{ - "self":"http://example.com:9001/v2/reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4be" - }, - "pattern":"smtp.example.com.", - "created_at":"2014-03-11T21:54:57.000000", - "updated_at":null, - "id":"RegionOne:c47229fb-0831-4b55-a5b5-380d361be4be", - } - ], - "links":{ - "self":"http://127.0.0.1:9001/v2/tlds" - } - } - - :form created_at: timestamp - :form updated_at: timestamp - :form name: tld name - :form id: uuid - :form description: UTF-8 text field - :form links: links to traverse the list - :statuscode 200: OK - :statuscode 401: Access Denied - - -Unset the PTR record for a FloatingIP -------------------------------------- - -.. http:patch:: /reverse/floatingips/(string:region):(uuid:floatingip_id) - - Unset a PTR record for the given FloatingIP. - - **Example request**: - - .. sourcecode:: http - - PATCH /reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1 - Host: example.com - Accept: application/json - Content-Type: application/json - - { - "ptrdname" : null, - } - - :statuscode 202: Pending - :statuscode 401: Access Denied - :statuscode 400: Invalid Object - :statuscode 404: FloatingIP / PTR Not found diff --git a/doc/source/rest/v2/service_status.rst b/doc/source/rest/v2/service_status.rst deleted file mode 100644 index f95d2c06d..000000000 --- a/doc/source/rest/v2/service_status.rst +++ /dev/null @@ -1,149 +0,0 @@ -.. - Copyright 2016 Hewlett Packard Enterprise Development Company LP - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Service Statuses -================ - -Overview ------------------------ -The Service Status entries are used to track the health state of the services -in the Designate system. - - -Get a Service Status --------------------- - -.. http:get:: /service_statuses/(uuid:id) - - Lists a particular Service Status - - **Example request**: - - .. sourcecode:: http - - GET /service_statuses/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 HTTP/1.1 - Host: example.com - Accept: application/json - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json; charset=UTF-8 - - { - "capabilities": {}, - "created_at": "2016-03-08T09:20:23.000000", - "heartbeated_at": "2016-03-08T09:26:18.000000", - "hostname": "vagrant-ubuntu-trusty-64", - "id": "769e8ca2-f71e-48be-8dee-631492c91e41", - "links": { - "self": "http://192.168.27.100:9001/v2/service_statuses/769e8ca2-f71e-48be-8dee-631492c91e41", - "service_status": "http://192.168.27.100:9001/v2/service_statuses/769e8ca2-f71e-48be-8dee-631492c91e41" - }, - "service_name": "pool_manager", - "stats": {}, - "status": "UP", - "updated_at": "2016-03-08T09:26:18.000000" - } - - :form created_at: timestamp - :form updated_at: timestamp - :form id: uuid - :form description: UTF-8 text field - :form links: links to traverse the list - :form service_name: Service name - :form hostname: Service hostname - :form capabilities: Service capabilities - dict of capabilities - :form stats: Service stats - dict of stats - :form status: Service status - UP, DOWN or WARNING - :statuscode 200: OK - :statuscode 401: Access Denied - :statuscode 404: Service Status not found - -List Service Statuses ---------------------- - -.. http:get:: /service_statuses - - Lists all Service Statuses - - **Example request**: - - .. sourcecode:: http - - GET /service_statuses HTTP/1.1 - Host: example.com - Accept: application/json - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json; charset=UTF-8 - - { - "service_statuses":[ - { - "capabilities": {}, - "created_at": "2016-03-08T09:20:23.000000", - "heartbeated_at": "2016-03-08T09:26:18.000000", - "hostname": "vagrant-ubuntu-trusty-64", - "id": "769e8ca2-f71e-48be-8dee-631492c91e41", - "links": { - "self": "http://192.168.27.100:9001/v2/service_statuses/769e8ca2-f71e-48be-8dee-631492c91e41", - "service_status": "http://192.168.27.100:9001/v2/service_statuses/769e8ca2-f71e-48be-8dee-631492c91e41" - }, - "service_name": "pool_manager", - "stats": {}, - "status": "UP", - "updated_at": "2016-03-08T09:26:18.000000" - }, - { - "capabilities": {}, - "created_at": "2016-03-08T09:20:26.000000", - "heartbeated_at": "2016-03-08T09:26:16.000000", - "hostname": "vagrant-ubuntu-trusty-64", - "id": "adcf580b-ea1c-4ebc-8a95-37ccdeed11ae", - "links": { - "self": "http://192.168.27.100:9001/v2/service_statuses/adcf580b-ea1c-4ebc-8a95-37ccdeed11ae", - "service_status": "http://192.168.27.100:9001/v2/service_statuses/adcf580b-ea1c-4ebc-8a95-37ccdeed11ae" - }, - "service_name": "zone_manager", - "stats": {}, - "status": "UP", - "updated_at": "2016-03-08T09:26:17.000000" - } - ], - "links":{ - "self":"http://127.0.0.1:9001/v2/service_statuses" - } - } - - :form created_at: timestamp - :form updated_at: timestamp - :form id: uuid - :form description: UTF-8 text field - :form links: links to traverse the list - :form service_name: Service name - :form hostname: Service hostname - :form capabilities: Service capabilities - dict of capabilities - :form stats: Service stats - dict of stats - :form status: Service status - UP, DOWN or WARNING - :statuscode 200: OK - :statuscode 401: Access Denied diff --git a/doc/source/rest/v2/tlds.rst b/doc/source/rest/v2/tlds.rst deleted file mode 100644 index 26e29af9a..000000000 --- a/doc/source/rest/v2/tlds.rst +++ /dev/null @@ -1,269 +0,0 @@ -.. - Copyright (c) 2014 Rackspace Hosting - All Rights Reserved. - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Tlds -======= - -Overview ------------------------ -Tld (Top level domain) entries are used to manage the Tlds that Designate recognizes. -By default, only an admin can manage these entries. The Tlds are stored in the :ref:`database` -in the table *tlds* and are not propagated to the :ref:`dns-backend`. By default when -Designate starts up there are no Tlds in the database. - -Tld Checks ------------------------ -When there are no Tld entries in the database, Tld checks are not enforced and -any domain/zone name can be created, as long as it adheres to the domain name schema. -When there are Tlds present in the database, then when a domain/zone is created -the name has to pass the following checks. - -#. The last label in the domain/zone name must be present as a Tld entry in the database. - e.g. If a domain/zone with the name *example.com.* is being created then the entry *com* must be present in the database. - -#. The domain/zone name must not be present as a Tld entry in the database. - e.g. If there is a Tld entry *co.uk* in the database, then a domain/zone with the name *co.uk.* cannot be created. - -Create Tld -------------- - -.. http:post:: /tlds - - Create a tld. *name* is the only entry that is required. The *name* should - not end in a period (.). - - **Example request**: - - .. sourcecode:: http - - POST /tlds HTTP/1.1 - Host: example.com - Accept: application/json - Content-Type: application/json - - { - "name" : "com", - "description" : "Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt" - } - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 201 Created - Content-Type: application/json; charset=UTF-8 - Location: http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 - - { - "description":"Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt", - "links":{ - "self":"http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9" - }, - "created_at":"2014-01-23T18:39:26.710827", - "updated_at":null, - "id":"5abe514c-9fb5-41e8-ab73-5ed25f8a73e9", - "name":"com" - } - - - :form created_at: timestamp - :form updated_at: timestamp - :form name: tld name - :form id: uuid - :form description: UTF-8 text field - :form links: links to traverse the list - :statuscode 201: Created - :statuscode 401: Access Denied - :statuscode 400: Invalid Object - :statuscode 409: Duplicate Tld - -Get a Tld -------------- - -.. http:get:: /tlds/(uuid:id) - - Lists a particular Tld - - **Example request**: - - .. sourcecode:: http - - GET /tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 HTTP/1.1 - Host: example.com - Accept: application/json - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json; charset=UTF-8 - - { - "description":"Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt", - "links":{ - "self":"http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9" - }, - "created_at":"2014-01-23T18:39:26.710827", - "updated_at":null, - "id":"5abe514c-9fb5-41e8-ab73-5ed25f8a73e9", - "name":"com" - } - - :form created_at: timestamp - :form updated_at: timestamp - :form name: tld name - :form id: uuid - :form description: UTF-8 text field - :form links: links to traverse the list - :statuscode 200: OK - :statuscode 401: Access Denied - :statuscode 404: Tld not found - -List Tlds ------------- - -.. http:get:: /tlds - - Lists all tlds - - **Example request**: - - .. sourcecode:: http - - GET /tlds HTTP/1.1 - Host: example.com - Accept: application/json - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json; charset=UTF-8 - - { - "tlds":[ - { - "description":"Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt", - "links":{ - "self":"http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9" - }, - "created_at":"2014-01-23T18:39:26.710827", - "updated_at":null, - "id":"5abe514c-9fb5-41e8-ab73-5ed25f8a73e9", - "name":"com" - }, - { - "description":"Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt", - "links":{ - "self":"http://127.0.0.1:9001/v2/tlds/46e50ebc-1b51-41ee-bc1f-8e75a470c5be" - }, - "created_at":"2014-01-23T19:59:53.985455", - "updated_at":null, - "id":"46e50ebc-1b51-41ee-bc1f-8e75a470c5be", - "name":"net" - } - ], - "links":{ - "self":"http://127.0.0.1:9001/v2/tlds" - } - } - - :form created_at: timestamp - :form updated_at: timestamp - :form name: tld name - :form id: uuid - :form description: UTF-8 text field - :form links: links to traverse the list - :statuscode 200: OK - :statuscode 401: Access Denied - -Update a Tld ---------------- - -.. http:patch:: /tlds/(uuid:id) - - updates a tld - - **Example request**: - - .. sourcecode:: http - - PATCH /tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 HTTP/1.1 - Host: example.com - Accept: application/json - Content-Type: application/json - - { - "name" : "org", - "description" : "Updated the name from com to org" - } - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json; charset=UTF-8 - - { - "description":"Updated the name from com to org", - "links":{ - "self":"http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9" - }, - "created_at":"2014-01-23T18:39:26.710827", - "updated_at":"2014-01-23T20:35:12.449599", - "id":"5abe514c-9fb5-41e8-ab73-5ed25f8a73e9", - "name":"org" - } - - :form created_at: timestamp - :form updated_at: timestamp - :form name: tld name - :form id: uuid - :form description: UTF-8 text field - :form links: links to traverse the list - :statuscode 200: OK - :statuscode 401: Access Denied - :statuscode 404: Tld not found - :statuscode 409: Duplicate Tld - -Delete a Tld ---------------- - -.. http:delete:: /tlds/(uuid:id) - - delete a tld - - **Example request**: - - .. sourcecode:: http - - DELETE /tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 HTTP/1.1 - Host: example.com - - **Example response**: - - .. sourcecode:: http - - HTTP/1.1 204 No Content - Content-Type: application/json; charset=UTF-8 - Content-Length: 0 - - :statuscode 204: No Content - :statuscode 401: Access Denied - :statuscode 404: Tld not found diff --git a/doc/source/rest/v2/tsigkeys.rst b/doc/source/rest/v2/tsigkeys.rst deleted file mode 100644 index f1cbb22dc..000000000 --- a/doc/source/rest/v2/tsigkeys.rst +++ /dev/null @@ -1,265 +0,0 @@ -.. - Copyright 2015 NEC Corporation. All rights reserved. - - Author: Sonu Kumar - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -======= -Tsigkey -======= - -Transaction signatures (TSIG) is a mechanism used to secure DNS messages and -to provide secure server-to-server communication (usually between master and -slave server, but can be extended for dynamic updates as well). - -Transaction Signatures, or TSIG for short, add cryptographic signatures as a -method of authenticating a DNS conversation. It uses a shared secret to -establish trust between the communicating parties. - - -Create Tsigkeys -=============== - -.. http:post:: /tsigkeys - - Create a new Tsigkey. - - **Example request**: - - .. code-block:: http - - POST /tsigkeys HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - { - "name": "Example key", - "algorithm": "hmac-sha256", - "secret": "SomeSecretKey", - "scope": "POOL", - "resource_id": "6ca6baef-3305-4ad0-a52b-a82df5752b62" - } - - **Example response**: - - .. code-block:: http - - HTTP/1.1 201 Created - Location: http://127.0.0.1:9001/v2/tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2 - Content-Length: 350 - Content-Type: application/json; charset=UTF-8 - - { - "links": { - "self": "http://127.0.0.1:9001/v2/tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2" - }, - "name": "test-key", - "algorithm": "hmac-sha256", - "resource_id": "6ca6baef-3305-4ad0-a52b-a82df5752b62", - "created_at": "2015-12-21T09:48:15.000000", - "updated_at": null, - "secret": "SomeSecretKey", - "scope": "POOL", - "id": "5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2" - } - - :form name: TSIG Key Name. - :form algorithm: TSIG Algorithm. - :form resource_id: Pool id or Zone id - :form secret: TSIG Secret. - :form scope: TSIG Scope. - - :statuscode 201: Created - :statuscode 202: Accepted - :statuscode 401: Access Denied - - -Get Tsigkeys -============ - -.. http:get:: /tsigkeys - - Get the list of Tsigkeys. - - **Example request**: - - .. code-block:: http - - GET /tsigkeys HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - - **Example response**: - - .. code-block:: http - - HTTP/1.1 200 OK - Content-Length: 776 - Content-Type: application/json; charset=UTF-8 - - { - "tsigkeys": [ - { - "links": { - "self": "http://127.0.0.1:9001/v2/tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2" - }, - "name": "test-key", - "algorithm": "hmac-sha256", - "resource_id": "6ca6baef-3305-4ad0-a52b-a82df5752b62", - "created_at": "2015-12-21T09:48:15.000000", - "updated_at": null, - "secret": "SomeSecretKey", - "scope": "POOL", - "id": "5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2" - }, - { - "links": { - "self": "http://127.0.0.1:9001/v2/tsigkeys/319c58fd-a0e0-4d69-a854-98bc49594419" - }, - "name": "test-key-2", - "algorithm": "hmac-sha256", - "resource_id": "6ca6baef-3305-4ad0-a52b-a82df5752b62", - "created_at": "2015-12-21T09:51:06.000000", - "updated_at": null, - "secret": "SomeSecretKey", - "scope": "POOL", - "id": "319c58fd-a0e0-4d69-a854-98bc49594419"} - ], - "links": { - "self": "http://127.0.0.1:9001/v2/tsigkeys"} - } - - :statuscode 200: Success - :statuscode 401: Access Denied - - - -Get Tsigkey -=========== - -.. http:get:: /tsigkeys/(uuid:id) - - Retrieves a tsigkey with the specified tsigkey's ID. - - **Example request:** - - .. sourcecode:: http - - GET /v2/tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2 HTTP/1.1 - Host: 127.0.0.1:9001 - Content-Type: application/json - Accept: application/json - - **Example response:** - - .. sourcecode:: http - - Content-Length: 350 - Content-Type: application/json; charset=UTF-8 - X-Openstack-Request-Id: req-d8cd7f24-a735-400b-9a4b-79e175efc923 - Date: Mon, 21 Dec 2015 09:59:26 GMT - - { - "links": { - "self": "http://127.0.0.1:9001/v2/tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2" - }, - "name": "test-key", - "algorithm": "hmac-sha256", - "resource_id": "6ca6baef-3305-4ad0-a52b-a82df5752b62", - "created_at": "2015-12-21T09:48:15.000000", - "updated_at": null, - "secret": "SomeSecretKey", - "scope": "POOL", - "id": "5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2" - } - - - -Update Tsigkey -============== - -.. http:patch:: /tsigkeys/(uuid:id) - - Update a Tsigkey with the specified tsigkey's id. - - **Example request**: - - .. code-block:: http - - PATCH /tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2 HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - { - "name": "example_tsigkey", - "scope": "ZONE" - } - - **Example response**: - - .. code-block:: http - - HTTP/1.1 200 OK - Content-Length: 381 - Content-Type: application/json; charset=UTF-8 - - { - "links": { - "self": "http://127.0.0.1:9001/v2/tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2" - }, - "name": "example_tsigkey", - "algorithm": "hmac-sha256", - "resource_id": "6ca6baef-3305-4ad0-a52b-a82df5752b62", - "created_at": "2015-12-21T09:48:15.000000", - "updated_at": "2015-12-21T10:02:18.000000", - "secret": "SomeSecretKey", - "scope": "ZONE", - "id": "5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2" - } - - :form name: TSIG Key Name. - :form algorithm: TSIG Algorithm. - :form resource_id: Pool id or Zone id - :form secret: TSIG Secret. - :form scope: TSIG Scope. - - :statuscode 200: Success - :statuscode 202: Accepted - :statuscode 401: Access Denied - -Remove Tsigkey -============== - -.. http:delete:: /tsigkeys/(uuid:id) - - Remove a Tsigkey with the specified tsigkey's id. - - **Example request**: - - .. code-block:: http - - DELETE /tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2 HTTP/1.1 - Accept: application/json - - **Example response**: - - .. code-block:: http - - HTTP/1.1 204 No Content - Content-Length: 0 - - :statuscode 400: Bad Request - :statuscode 204: Successfully Deleted diff --git a/doc/source/rest/v2/zones.rst b/doc/source/rest/v2/zones.rst deleted file mode 100644 index 3e943e06e..000000000 --- a/doc/source/rest/v2/zones.rst +++ /dev/null @@ -1,1105 +0,0 @@ -.. - Copyright (C) 2014 eNovance SAS - - Author: Artom Lifshitz - - Licensed under the Apache License, Version 2.0 (the "License"); you may - not use this file except in compliance with the License. You may obtain - a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, WITHOUT - WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the - License for the specific language governing permissions and limitations - under the License. - -Zones -===== - -A zone resource corresponds to the classical DNS zone. - -Create Zone ------------ - -.. http:post:: /zones - - Creates a new zone. - - **Example request:** - - .. sourcecode:: http - - POST /v2/zones HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - { - "name": "example.org.", - "email": "joe@example.org", - "ttl": 7200, - "description": "This is an example zone." - } - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66", - "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" - } - } - - :form description: UTF-8 text field. - :form name: Valid zone name (Immutable). - :form type: Enum PRIMARY/SECONDARY, default PRIMARY (Immutable). - :form email: email address, required for type PRIMARY, NULL for SECONDARY. - :form ttl: time-to-live numeric value in seconds, NULL for SECONDARY. - :form masters: Array of master nameservers. (NULL for type PRIMARY, required for SECONDARY otherwise zone will not be transferred before set). - - :statuscode 201: Created - :statuscode 202: Accepted - :statuscode 401: Access Denied - -Get Zone --------- - -.. http:get:: /zones/(uuid:id) - - Retrieves a zone with the specified zone ID. - - **Example request:** - - .. sourcecode:: http - - GET /v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Vary: Accept - Content-Type: application/json - - { - "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66", - "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" - } - } - - :statuscode 200: Success - :statuscode 401: Access Denied - -Get Zone Name Servers ---------------------- - -.. http:get:: /zones/(uuid:id)/nameservers - - Retrieves the nameservers for a zone with zone_id of id - - **Example request:** - - .. sourcecode:: http - - GET /v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/nameservers HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Vary: Accept - Content-Type: application/json - - { - "nameservers": [ - { - "hostname": "ns1.example.com.", - "priority": 1 - }, - { - "hostname": "ns2.example.com.", - "priority": 2 - } - ] - } - - :statuscode 200: Success - :statuscode 401: Access Denied - -List Zones ----------- - -.. http:get:: /zones - - Lists all zones. - - **Example Request:** - - .. sourcecode:: http - - GET /v2/zones HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - - **Example Response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Vary: Accept - Content-Type: application/json - - { - "zones": [{ - "status": "ACTIVE", - "masters": [], - "name": "example.org.", - "links": { - "self": "http://127.0.0.1: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": "abc@example.com", - "description": null - }, - { - "status": "ACTIVE", - "masters": [], - "name": "example1.org.", - "links": { - "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": "http://127.0.0.1:9001/v2/zones" - }, - "metadata": { - "total_count": 2 - } - } - - :statuscode 200: Success - :statuscode 401: Access Denied - -Update Zone ------------ - -.. http:patch:: /zones/(uuid:id) - - Changes the specified attribute(s) for an existing zone. - - In the example below, we update the TTL to 3600. - - **Request:** - - .. sourcecode:: http - - PATCH /v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - { - "ttl": 3600 - } - - **Response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3", - "pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2", - "project_id": "4335d1f0-f793-11e2-b778-0800200c9a66", - "name": "example.org.", - "email": "joe@example.org.", - "ttl": 3600, - "serial": 1404760160, - "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": "2014-07-07T19:09:20.876366", - "links": { - "self": "https://127.0.0.1:9001/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3" - } - } - - :form description: UTF-8 text field. - :form name: Valid zone name (Immutable). - :form type: Enum PRIMARY/SECONDARY, default PRIMARY (Immutable). - :form email: email address, required for type PRIMARY, NULL for SECONDARY. - :form ttl: time-to-live numeric value in seconds, NULL for SECONDARY - :form masters: Array of master nameservers. (NULL for type PRIMARY, required for SECONDARY otherwise zone will not be transferred before set.) - - :statuscode 200: Success - :statuscode 202: Accepted - :statuscode 401: Access Denied - -Delete Zone ------------ - -.. http:delete:: zones/(uuid:id) - - Deletes a zone with the specified zone ID. Deleting a zone is asynchronous. - Once pool manager has deleted the zone from all the pool targets, the zone - is deleted from storage. - - **Example Request:** - - .. sourcecode:: http - - DELETE /v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - **Example Response:** - - .. sourcecode:: http - - HTTP/1.1 202 Accepted - - :statuscode 202: Accepted - - -Abandon Zone ------------- - -.. http:post:: /zones/(uuid:id)/tasks/abandon - - When a zone is abandoned it removes the zone from Designate's storage. - There is no operation done on the pool targets. This is intended to be used - in the cases where Designate's storage is incorrect for whatever reason. By - default this is restricted by policy (abandon_domain) to admins. - - **Example Request:** - - .. sourcecode:: http - - POST /v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/tasks/abandon HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - **Example Response:** - - .. sourcecode:: http - - HTTP/1.1 204 No content - - :statuscode 204: No content - -Transfer Zone -------------- - -Create Zone Transfer Request -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. http:post:: /zones/(uuid:id)/tasks/transfer_requests - - To initiate a transfer the original owner must create a transfer request. - - This will return two items that are required to continue: - * key: a password that is used to validate the transfer - * id: ID of the request. - - Both of these should be communicated out of band (email / IM / etc) to the intended recipient - - There is an option of limiting the transfer to a single project. If that is required, the person initiating the transfer - will need the Project ID. This will also allow the targeted project to see the transfer in their list of requests. - - A non-targeted request will not show in a list operation, apart from the owning projects request. - An targeted request will only show in the targets and owners lists. - - An untargeted request can be viewed by any authenticated user. - - **Example Request** - - .. sourcecode:: http - - POST /v2/zones/6b78734a-aef1-45cd-9708-8eb3c2d26ff8/tasks/transfer_requests HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - { - "target_project_id": "123456", - "description": "Transfer qa.dev.example.com. to QA Team" - } - - **Example Response** - - .. sourcecode:: http - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "created_at": "2014-07-17T20:34:40.882579", - "description": null, - "id": "f2ad17b5-807a-423f-a991-e06236c247be", - "key": "9Z2R50Y0", - "project_id": "1", - "status": "ACTIVE", - "target_project_id": "123456", - "updated_at": null, - "zone_id": "6b78734a-aef1-45cd-9708-8eb3c2d26ff8", - "zone_name": "qa.dev.example.com.", - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests/f2ad17b5-807a-423f-a991-e06236c247be" - } - } - - :form description: UTF-8 text field - :form target_project_id: Optional field to only allow a single tenant to accept the transfer request - - -List Zone Transfer Requests -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. http:get:: /zones/tasks/transfer_requests - - List all transfer requests that the requesting project have created, or are targeted to that project - - The detail shown will differ, based on who the requester is. - - **Example Request** - - .. sourcecode:: http - - GET /zones/tasks/transfer_requests HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - - **Example Response** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "transfer_requests": [ - { - "created_at": "2014-07-17T20:34:40.882579", - "description": "This was created by the requesting project", - "id": "f2ad17b5-807a-423f-a991-e06236c247be", - "key": "9Z2R50Y0", - "project_id": "1", - "status": "ACTIVE", - "target_project_id": "123456", - "updated_at": null, - "zone_id": "6b78734a-aef1-45cd-9708-8eb3c2d26ff8", - "zone_name": "qa.dev.example.com.", - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests/f2ad17b5-807a-423f-a991-e06236c247be" - } - }, - { - "description": "This is scoped to the requesting project", - "id": "efd2d720-b0c4-43d4-99f7-d9b53e08860d", - "zone_id": "2c4d5e37-f823-4bee-9859-031cb44f80e7", - "zone_name": "subdomain.example.com.", - "status": "ACTIVE", - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests/efd2d720-b0c4-43d4-99f7-d9b53e08860d" - } - } - ], - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests" - } - } - - -View a Transfer Request -^^^^^^^^^^^^^^^^^^^^^^^ - -.. http:get:: /zones/tasks/transfer_requests/(uuid:id) - - Show details about a request. - - This allows a user to view a transfer request before accepting it - - **Example Request** - - .. sourcecode:: http - - GET /v2/zones/tasks/transfer_requests/f2ad17b5-807a-423f-a991-e06236c247be HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - - **Example Response** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "description": "This is scoped to the requesting project", - "id": "efd2d720-b0c4-43d4-99f7-d9b53e08860d", - "zone_id": "2c4d5e37-f823-4bee-9859-031cb44f80e7", - "zone_name": "subdomain.example.com.", - "status": "ACTIVE", - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests/efd2d720-b0c4-43d4-99f7-d9b53e08860d" - } - } - - -Update a Transfer Request -^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. http: patch:: /zones/tasks/transfer_requests/(uuid:id) - - Update a transfer request. - - This allows a user to update a transfer request before accepting it. - - **Example Request** - - .. sourcecode:: http - - PATCH v2/zones/tasks/transfer_requests/b853202b-22f9-49c1-893d-49cbbf6830bb HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content: application/json - - { - "description": "demo_transfer" - } - - **Example Response** - - ..sourcecode:: http - - HTTP/1.1 200 OK - Content-Length: 476 - Content-Type: application/json - charset=UTF-8 - - { - "status": "ACTIVE", - "target_project_id": dc685ea10a3a4ddfb9bc2deeca66f131, - "zone_id": "08615081-cbfd-445e-9d35-15fccf2be4be", - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_requests/b853202b-22f9-49c1-893d-49cbbf6830bb" - }, - "created_at": "2016-01-28T04:43:00.000000", - "updated_at": "2016-01-28T04:45:17.000000", - "key": "XWUR5VFL", - "zone_name": "example.com.", - "project_id": "dc685ea10a3a4ddfb9bc2deeca66f131", - "id": "b853202b-22f9-49c1-893d-49cbbf6830bb", - "description": "demo_transfer" - } - - :statuscode 200: Success - :statuscode 202: Accepted - :statuscode 401: Access Denied - - :form description: UTF-8 text field - - -Delete a transfer request -^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. http: delete:: /zones/tasks/transfer_requests/(uuid:id) - - Delete a zone transfer request with the specified id. - - **Example Request** - - .. sourcecode:: http - - DELETE /v2/zones/tasks/transfer_requests/"b853202b-22f9-49c1-893d-49cbbf6830bb HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content: application/json - - **Example Response** - - .. sourcecode:: http - - HTTP/1.1 204 No Content - - :statuscode 204: No Content - - -Accept a Transfer Request -^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. http:post:: /zones/tasks/transfer_accepts - - Accept a zone transfer request. This is called by the project that will own the zone - (i.e. the project that will maintain the zone) - - Once the API returns "Complete" the zone has been transferred to the new project - - **Example Request** - - .. sourcecode:: http - - POST /v2/zones/tasks/transfer_accepts HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - { - "key":"J6JCET2C", - "zone_transfer_request_id":"98ba1d22-c092-4603-891f-8a0ab04f7e57" - } - - **Example Response** - - .. sourcecode:: http - - HTTP/1.1 201 Created - Content-Length: 532 - Content-Type: application/json - charset=UTF-8 - - { - "status": "COMPLETE", - "zone_id": "53cdcf82-9e32-4a00-a90d-32d6ec5db7e9", - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_accepts/46b04776-a7c9-45b4-812e-b8e615d1d73b", - "zone": "http://127.0.0.1:9001/v2/zones/53cdcf82-9e32-4a00-a90d-32d6ec5db7e9" - }, - "created_at": "2016-05-13 08:01:16", - "updated_at": "2016-05-13 08:01:16", - "key": "J6JCET2C", - "project_id": "10457ad1fe074f4a89bb1e4c0cd83d40", - "id": "46b04776-a7c9-45b4-812e-b8e615d1d73b", - "zone_transfer_request_id": "98ba1d22-c092-4603-891f-8a0ab04f7e57" - } - - -View a Transfer Accept -^^^^^^^^^^^^^^^^^^^^^^ - -.. http:get:: /zones/tasks/transfer_accepts/(uuid:id) - - **Example Request** - - .. sourcecode:: http - - GET /v2/zones/tasks/transfer_accepts/46b04776-a7c9-45b4-812e-b8e615d1d73b HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - - **Example Response** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Length: 526 - Content-Type: application/json - charset=UTF-8 - - { - "status": "COMPLETE", - "zone_id": "53cdcf82-9e32-4a00-a90d-32d6ec5db7e9", - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_accepts/46b04776-a7c9-45b4-812e-b8e615d1d73b", - "zone": "http://127.0.0.1:9001/v2/zones/53cdcf82-9e32-4a00-a90d-32d6ec5db7e9" - }, - "created_at": "2016-05-13 08:01:16", - "updated_at": "2016-05-13 08:01:16", - "key": null, - "project_id": "10457ad1fe074f4a89bb1e4c0cd83d40", - "id": "46b04776-a7c9-45b4-812e-b8e615d1d73b", - "zone_transfer_request_id": "98ba1d22-c092-4603-891f-8a0ab04f7e57" - } - - -Import Zone ------------ - -Create a Zone Import -^^^^^^^^^^^^^^^^^^^^ - -.. http:post:: /zones/tasks/imports - - To import a zonefile, set the Content-type to **text/dns** . The - **zoneextractor.py** tool in the **contrib** folder can generate zonefiles - that are suitable for Designate (without any **$INCLUDE** statements for - example). - - An object will be returned that can be queried using the 'self' link the - 'links' field. - - **Example request:** - - .. sourcecode:: http - - POST /v2/zones/tasks/imports HTTP/1.1 - Host: 127.0.0.1:9001 - Content-type: text/dns - - $ORIGIN example.com. - example.com. 42 IN SOA ns.example.com. nsadmin.example.com. 42 42 42 42 42 - example.com. 42 IN NS ns.example.com. - example.com. 42 IN MX 10 mail.example.com. - ns.example.com. 42 IN A 10.0.0.1 - mail.example.com. 42 IN A 10.0.0.2 - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 201 Created - Content-Type: application/json - - { - "status": "PENDING", - "zone_id": null, - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/imports/074e805e-fe87-4cbb-b10b-21a06e215d41" - }, - "created_at": "2015-05-08T15:43:42.000000", - "updated_at": null, - "version": 1, - "message": null, - "project_id": "1", - "id": "074e805e-fe87-4cbb-b10b-21a06e215d41" - } - - :statuscode 202: Accepted - :statuscode 415: Unsupported Media Type - - -View a Zone Import -^^^^^^^^^^^^^^^^^^ - -.. http:get:: /zones/tasks/imports/(uuid:id) - - The status of a zone import can be viewed by querying the id - given when the request was created. - - **Example request:** - - .. sourcecode:: http - - GET /v2/zones/tasks/imports/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "status": "COMPLETE", - "zone_id": "6625198b-d67d-47dc-8d29-f90bd60f3ac4", - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/imports/074e805e-fe87-4cbb-b10b-21a06e215d41", - "href": "http://127.0.0.1:9001/v2/zones/6625198b-d67d-47dc-8d29-f90bd60f3ac4" - }, - "created_at": "2015-05-08T15:43:42.000000", - "updated_at": "2015-05-08T15:43:42.000000", - "version": 2, - "message": "example.com. imported", - "project_id": "noauth-project", - "id": "074e805e-fe87-4cbb-b10b-21a06e215d41" - } - - :statuscode 200: Success - :statuscode 401: Access Denied - :statuscode 404: Not Found - - Notice the status has been updated, the message field shows that the zone was - successfully imported, and there is now a 'href' in the 'links' field that points - to the new zone. - -List Zone Imports -^^^^^^^^^^^^^^^^^ - -.. http:get:: /zones/tasks/imports/ - - List all of the zone imports created by this project. - - **Example request:** - - .. sourcecode:: http - - GET /v2/zones/tasks/imports/ HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "imports": [ - { - "status": "COMPLETE", - "zone_id": 047888ee-e9dd-4c08-8b44-ab2e879e01bd, - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/imports/0436a86e-ffc1-4d38-82a7-d75170fcd2a9", - "href": "http://127.0.0.1:9001/v2/zones/047888ee-e9dd-4c08-8b44-ab2e879e01bd" - }, - "created_at": "2016-04-05T06:03:06.000000", - "updated_at": "2016-04-05T06:03:06.000000", - "version": 2, - "message": "example.com. imported", - "project_id": "1de6e2fdc22342d3bef6340c7b70f497", - "id": "0436a86e-ffc1-4d38-82a7-d75170fcd2a9" - }, - { - "status": "COMPLETE", - "zone_id": 68a17870-7f81-470a-b5e9-2753460fd6dc, - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/imports/f0aa4ac1-f975-46a4-b417-339acd1ea8e3", - "href": "http://127.0.0.1:9001/v2/zones/68a17870-7f81-470a-b5e9-2753460fd6dc" - }, - "created_at": "2016-04-05T06:06:26.000000", - "updated_at": "2016-04-05T06:06:26.000000", - "version": 2, - "message": "temp.org. imported", - "project_id": "1de6e2fdc22342d3bef6340c7b70f497", - "id": "f0aa4ac1-f975-46a4-b417-339acd1ea8e3" - } - ], - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/imports" - }, - "metadata": { - "total_count": 2 - } - } - - :statuscode 200: Success - :statuscode 401: Access Denied - :statuscode 404: Not Found - -Delete Zone Import -^^^^^^^^^^^^^^^^^^ - -.. http:delete:: /zones/tasks/imports/(uuid:id) - - Deletes a zone import with the specified ID. This does not affect the zone - that was imported, it simply removes the record of the import. - - **Example Request:** - - .. sourcecode:: http - - DELETE /v2/zones/tasks/imports/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - **Example Response:** - - .. sourcecode:: http - - HTTP/1.1 204 No Content - - :statuscode 204: No Content - -Export Zone ------------ - -Create a Zone Export -^^^^^^^^^^^^^^^^^^^^ - -.. http:post:: /zones/(uuid:id)/tasks/export - - To export a zone in BIND9 zonefile format, a zone export resource must be - created. This is accomplished by initializing an export task. - - **Example request:** - - .. sourcecode:: http - - POST /v2/zones/074e805e-fe87-4cbb-b10b-21a06e215d41/tasks/export HTTP/1.1 - Host: 127.0.0.1:9001 - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 202 Accepted - Content-Type: application/json - - { - "status": "PENDING", - "zone_id": "074e805e-fe87-4cbb-b10b-21a06e215d41", - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/exports/8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720" - }, - "created_at": "2015-08-27T20:57:03.000000", - "updated_at": null, - "version": 1, - "location": null, - "message": null, - "project_id": "1", - "id": "8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720" - } - - :statuscode 202: Accepted - -View a Zone Export Record -^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. http:get:: /zones/tasks/exports/(uuid:id) - - The status of a zone export can be viewed by querying the id - given when the request was created. - - **Example request:** - - .. sourcecode:: http - - GET /v2/zones/tasks/exports/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - "status": "COMPLETE", - "zone_id": "6625198b-d67d-47dc-8d29-f90bd60f3ac4", - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/exports/8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720", - "export": "http://127.0.0.1:9001/v2/zones/tasks/exports/8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720/export" - }, - "created_at": "2015-08-27T20:57:03.000000", - "updated_at": "2015-08-27T20:57:03.000000", - "version": 2, - "location": "designate://v2/zones/tasks/exports/8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720/export", - "message": null, - "project_id": "noauth-project", - "id": "8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720" - } - - :statuscode 200: Success - :statuscode 401: Access Denied - :statuscode 404: Not Found - - Notice the status has been updated and there is now an 'export' in the 'links' field that points - to a link where the export (zonefile) can be accessed. - - -View the Exported Zone -^^^^^^^^^^^^^^^^^^^^^^ - -The link that is generated in the export field in an export resource can be followed to -a Designate resource, or an external resource. If the link is to a Designate endpoint, the -zonefile can be retrieved directly through the API by following that link. - -.. http:get:: /zones/tasks/exports/(uuid:id) - - **Example request:** - - .. sourcecode:: http - - GET /zones/tasks/exports/8ec17fe1-d1f9-41b4-aa98-4eeb4c27b720/export HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: text/dns - - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: text/dns - - $ORIGIN example.com. - $TTL 42 - - example.com. IN SOA ns.designate.com. nsadmin.example.com. ( - 1394213803 ; serial - 3600 ; refresh - 600 ; retry - 86400 ; expire - 3600 ; minimum - ) - - - example.com. IN NS ns.designate.com. - - - example.com. IN MX 10 mail.example.com. - ns.example.com. IN A 10.0.0.1 - mail.example.com. IN A 10.0.0.2 - - :statuscode 200: Success - :statuscode 401: Access Denied - :statuscode 404: Not Found - - Notice how the SOA and NS records are replaced with the Designate server(s). - -List Zone Exports -^^^^^^^^^^^^^^^^^ - -.. http:get:: /zones/tasks/exports/ - - List all of the zone exports created by this project. - - **Example request:** - - .. sourcecode:: http - - GET /v2/zones/tasks/exports/ HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - - **Example response:** - - .. sourcecode:: http - - HTTP/1.1 200 OK - Content-Type: application/json - - { - - "exports": [ - { - "status": "COMPLETE", - "zone_id": "17a8d6b3-6ace-4857-b113-a707c5f975b1", - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/exports/204be410-0a9c-44b8-839e-bc4df3bb0d9a", - "export": "http://127.0.0.1:9001/v2/zones/tasks/exports/204be410-0a9c-44b8-839e-bc4df3bb0d9a/export" - }, - "created_at": "2016-04-04T01:53:29.000000", - "updated_at": "2016-04-04T01:53:29.000000", - "version": 2, - "location": "designate://v2/zones/tasks/exports/204be410-0a9c-44b8-839e-bc4df3bb0d9a/export", - "message": null, - "project_id": "1de6e2fdc22342d3bef6340c7b70f497", - "id": "204be410-0a9c-44b8-839e-bc4df3bb0d9a" - } - ], - "links": { - "self": "http://127.0.0.1:9001/v2/zones/tasks/exports" - }, - "metadata": { - "total_count": 1 - } - } - - :statuscode 200: Success - :statuscode 401: Access Denied - :statuscode 404: Not Found - -Delete Zone Export -^^^^^^^^^^^^^^^^^^ - -.. http:delete:: /zones/tasks/exports/(uuid:id) - - Deletes a zone export with the specified ID. This does not affect the zone - that was exported, it simply removes the record of the export. If the link - to view the export was pointing to a Designate API endpoint, the endpoint - will no longer be available. - - **Example Request:** - - .. sourcecode:: http - - DELETE /v2/zones/tasks/exports/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1 - Host: 127.0.0.1:9001 - Accept: application/json - Content-Type: application/json - - **Example Response:** - - .. sourcecode:: http - - HTTP/1.1 204 No Content - - :statuscode 204: No Content