Initial Pool API docs
Change-Id: Iecf252d4126a441dcf2700bc1ea4f79e2013d4c2
This commit is contained in:
Eric Larson
parent
6bf5ae1938
commit
0fd39ffe94
@ -76,3 +76,4 @@ V2 API
|
||||
rest/v2/tlds
|
||||
rest/v2/blacklists
|
||||
rest/v2/quotas
|
||||
rest/v2/pools
|
||||
|
||||
309
doc/source/rest/v2/pools.rst
Normal file
309
doc/source/rest/v2/pools.rst
Normal file
@ -0,0 +1,309 @@
|
||||
..
|
||||
Copyright (C) 2015 Rackspace
|
||||
|
||||
Author: Eric Larson <eric.larson@rackspace.com>
|
||||
|
||||
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
|
||||
Loading…
Reference in New Issue
Block a user