Zones¶

A zone resource corresponds to the classical DNS zone.

Create Zone¶

POST /zones¶

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

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

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

description – UTF-8 text field.
name – Valid zone name (Immutable).
type – Enum PRIMARY/SECONDARY, default PRIMARY (Immutable).
email – email address, required for type PRIMARY, NULL for SECONDARY.
ttl – time-to-live numeric value in seconds, NULL for SECONDARY.
masters – Array of master nameservers. (NULL for type PRIMARY, required for SECONDARY otherwise zone will not be transferred before set).

Status Codes:

201 Created – Created
202 Accepted – Accepted
401 Unauthorized – Access Denied

Get Zone¶

GET /zones/(uuid: id)¶

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

{
    "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:	200 OK – Success 401 Unauthorized – Access Denied

Get Zone Name Servers¶

GET /zones/(uuid: id)/nameservers¶

Retrieves the nameservers for a zone with zone_id of id

Example request:

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:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "nameservers": [
        {
            "hostname": "ns1.example.com.",
            "priority": 1
        },
        {
            "hostname": "ns2.example.com.",
            "priority": 2
        }
    ]
}

Status Codes:	200 OK – Success 401 Unauthorized – Access Denied

List Zones¶

GET /zones¶

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:	200 OK – Success 401 Unauthorized – Access Denied

Update Zone¶

PATCH /zones/(uuid: id)¶

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

{
    "ttl": 3600
}

Response:

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

description – UTF-8 text field.
name – Valid zone name (Immutable).
type – Enum PRIMARY/SECONDARY, default PRIMARY (Immutable).
email – email address, required for type PRIMARY, NULL for SECONDARY.
ttl – time-to-live numeric value in seconds, NULL for SECONDARY
masters – Array of master nameservers. (NULL for type PRIMARY, required for SECONDARY otherwise zone will not be transferred before set.)

Status Codes:

200 OK – Success
202 Accepted – Accepted
401 Unauthorized – Access Denied

Delete Zone¶

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:

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:	202 Accepted – Accepted

Abandon Zone¶

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:

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:	204 No Content – No content

Transfer Zone¶

Create Zone Transfer Request¶

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

{
    "target_project_id": "123456",
    "description": "Transfer qa.dev.example.com. to QA Team"
}

Example Response

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 Parameters:
	description – UTF-8 text field target_project_id – Optional field to only allow a single tenant to accept the transfer request

List Zone Transfer Requests¶

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

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

View a Transfer Request¶

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

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

{
    "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 Transfer Request¶

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

POST /v2/zones/tasks/transfer_accept HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json

{
    "key":"9Z2R50Y0",
    "zone_transfer_request_id":"f2ad17b5-807a-423f-a991-e06236c247be"
}

Example Response

HTTP/1.1 201 Created
Content-Type: application/json

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

OpenStack

Zones¶

Create Zone¶

Get Zone¶

Get Zone Name Servers¶

List Zones¶

Update Zone¶

Delete Zone¶

Abandon Zone¶

Transfer Zone¶

Create Zone Transfer Request¶

List Zone Transfer Requests¶

View a Transfer Request¶

Accept a Transfer Request¶

Incubated Project

Table Of Contents

Previous topic

Next topic

This Page

OpenStack

Zones¶

Create Zone¶

Get Zone¶

Get Zone Name Servers¶

List Zones¶

Update Zone¶

Delete Zone¶

Abandon Zone¶

Transfer Zone¶

Create Zone Transfer Request¶

List Zone Transfer Requests¶

View a Transfer Request¶

Accept a Transfer Request¶

Incubated Project

Table Of Contents

Previous topic

Next topic

This Page

Quick search