diff --git a/doc/source/rest.rst b/doc/source/rest.rst index b9f5391fe..e855fece4 100644 --- a/doc/source/rest.rst +++ b/doc/source/rest.rst @@ -76,3 +76,4 @@ V2 API rest/v2/tlds rest/v2/blacklists rest/v2/quotas + rest/v2/pools diff --git a/doc/source/rest/v2/pools.rst b/doc/source/rest/v2/pools.rst new file mode 100644 index 000000000..d66b88e3d --- /dev/null +++ b/doc/source/rest/v2/pools.rst @@ -0,0 +1,309 @@ +.. + 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 + + { + "pool": { + "attributes": {}, + "nameservers": [ + "ns1.example.org." + ], + "name": "example_pool" + } + } + + + **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 + + { + "pool": { + "description": null, + "id": "d1716333-8c16-490f-85ee-29af36907605", + "project_id": "noauth-project", + "created_at": "2015-02-23T21:56:33.000000", + "attributes": null, + "nameservers": [ + "ns1.example.org." + ], + "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 nameservers: a list of nameservers 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, + "nameservers": [ + "ns1.example.org." + ], + "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, + "nameservers": [ + "ns1.example.org." + ], + "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 + + { + "pool": { + "description": null, + "id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "project_id": null, + "created_at": "2015-02-18T22:18:58.000000", + "attributes": null, + "nameservers": [ + "ns1.example.org." + ], + "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 + + { + "pool": { + "nameservers": [ + "ns3.example.org." + ] + } + } + + **Example response**: + + .. code-block:: http + + HTTP/1.1 200 OK + Content-Length: 369 + Content-Type: application/json; charset=UTF-8 + + { + "pool": { + "description": null, + "id": "794ccc2c-d751-44fe-b57f-8894c9f5c842", + "project_id": null, + "created_at": "2015-02-18T22:18:58.000000", + "attributes": null, + "nameservers": [ + "ns1.example.org.", + "ns3.example.org." + ], + "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 + + { + "pool": { + "nameservers": ["ns3.example.org"] + } + } + + This would **replace** the value of the `nameservers` key. + + It is a good practice to peform 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