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

POST /pools

Create a new Pool.

Example request:

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:

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 Parameters:  

• name – UTF-8 text field
• description – a description of the pool
• tenant_id – the UUID of the tenant
• provisioner – the type backend that should be used
• attributes – meta data for the pool
• ns_records – a list of ns_records as fully qualified domains

Status Codes:

• 201 Created – Created
• 400 Bad Request – Bad Request
• 401 Unauthorized – Access Denied

Get Pools

GET /pools

Get the list of Pools. This resource supports the Collections API.

Example request:

GET /pools HTTP/1.1
Host: example.com
Accept: application/json

Example response:

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
    }
  ]
}

Status Codes:

• 200 OK – OK
• 400 Bad Request – Bad Request

Get Pool

GET /pools/(uuid: id)

Get a specific Pool using the Pool’s uuid id.

Example request:

GET /pools/d1716333-8c16-490f-85ee-29af36907605 HTTP/1.1
Host: example.com
Accept: application/json

Example response:

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"
}

Status Codes:

• 200 OK – OK
• 400 Bad Request – Bad Request

Update Pool

PATCH /pools/(uuid: id)

Update a Pool.

Example request:

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:

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

{
    "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.

Status Codes:

• 202 Accepted – Accepted
• 400 Bad Request – Bad Request
• 409 Conflict – Conflict

Remove Pool

DELETE /pools/(uuid: id)

Remove a Pool. When deleting a Pool, the Pool cannot contain any zones.

Example request:

DELETE /pools HTTP/1.1
Accept: application/json

Example response:

HTTP/1.1 204 No Content
Content-Length: 0

Status Codes:

• 400 Bad Request – Bad Request
• 204 No Content – Successfully Deleted