A zone resource corresponds to the classical DNS zone.
Creates a new zone.
Example request:
POST /v2/zones HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
{
"zone": {
"name": "example.org.",
"email": "joe@example.org",
"ttl": 7200,
"description": "This is an example zone."
}
}
Example response:
HTTP/1.1 201 Created
Content-Type: application/json
{
"zone": {
"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 Parameters: | |
---|---|
|
|
Status Codes: |
|
Retrieves a zone with the specified zone ID.
Example request:
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:
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"zone": {
"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"
}
}
}
Status Codes: |
|
---|
Lists all zones.
Example Request:
GET /v2/zones HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
Example Response:
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"zones": [{
"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"
}
}, {
"id": "fdd7b0dc-52a3-491e-829f-41d18e1d3ada",
"pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2",
"project_id": "4335d1f0-f793-11e2-b778-0800200c9a66",
"name": "example.net.",
"email": "joe@example.net.",
"ttl": 7200,
"serial": 1404756682,
"status": "ACTIVE",
"description": "This is another example zone.",
"masters": [],
"type": "PRIMARY",
"transferred_at": null,
"version": 1,
"created_at": "2014-07-07T18:22:08.287743",
"updated_at": null,
"links": {
"self": "https://127.0.0.1:9001/v2/zones/fdd7b0dc-52a3-491e-829f-41d18e1d3ada"
}
}],
"links": {
"self": "https://127.0.0.1:9001/v2/zones"
}
}
Status Codes: |
|
---|
Changes the specified attribute(s) for an existing zone.
In the example below, we update the TTL to 3600.
Request:
PATCH /v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
{
"zone": {
"ttl": 3600
}
}
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"zone": {
"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 Parameters: | |
---|---|
|
|
Status Codes: |
|
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:
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:
HTTP/1.1 202 Accepted
Status Codes: |
|
---|
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).
Example request:
POST /v2/zones 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:
HTTP/1.1 201 Created
Content-Type: application/json
{
"zone": {
"email": "nsadmin@example.com",
"id": "6b78734a-aef1-45cd-9708-8eb3c2d26ff1",
"links": {
"self": "http://127.0.0.1:9001/v2/zones/6b78734a-aef1-45cd-9708-8eb3c2d26ff1"
},
"name": "example.com.",
"pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2",
"project_id": "d7accc2f8ce343318386886953f2fc6a",
"serial": 1404757531,
"ttl": "42",
"created_at": "2014-07-07T18:25:31.275934",
"updated_at": null,
"version": 1,
"masters": [],
"type": "PRIMARY",
"transferred_at": null
}
}
Status Codes: |
|
---|
To export a zone in zonefile format, set the Accept header to text/dns.
Example request
GET /v2/zones/6b78734a-aef1-45cd-9708-8eb3c2d26ff1 HTTP/1.1
Host: 127.0.0.1:9001
Accept: text/dns
Example response
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
Status Codes: |
|
---|
Notice how the SOA and NS records are replaced with the Designate server(s).
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:
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:
HTTP/1.1 204 No content
Status Codes: |
|
---|
To initiate a transfer the original owner must create a transfer 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 un-targeted request can be viewed by any authenticated user.
Example Request
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
{
"transfer_request":{
"target_project_id": "123456",
"description": "Transfer qa.dev.example.com. to QA Team"
}
}
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"transfer_request": {
"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 Parameters: | |
---|---|
|
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
GET /zones/tasks/transfer_requests HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Example Response
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"
}
}
Show details about a request.
This allows a user to view a transfer request before accepting it
Example Request
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"transfer_request":{
"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"
}
}
}
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
POST /v2/zones/tasks/transfer_accept HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
{
"transfer_accept":{
"key":"9Z2R50Y0",
"zone_transfer_request_id":"f2ad17b5-807a-423f-a991-e06236c247be"
}
}
Example Response
HTTP/1.1 201 Created
Content-Type: application/json
{
"transfer_accept": {
"id": "581891d5-99f5-49e1-86c3-eec0f44d66fd",
"links": {
"self": "http://127.0.0.1:9001/v2/zones/tasks/transfer_accepts/581891d5-99f5-49e1-86c3-eec0f44d66fd",
"zone": "http://127.0.0.1:9001/v2/zones/6b78734a-aef1-45cd-9708-8eb3c2d26ff8"
},
"status": "COMPLETE"
}
}