openstack/designate
Code Issues Proposed changes

Merge "Move APIv2 Docs to api-ref site"

Browse Source
This commit is contained in:
Jenkins 2016-07-06 13:46:48 +00:00 committed by Gerrit Code Review
commit 6395765b82
12 changed files with 7 additions and 4068 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/source/production-guidelines.rst
View File

@ -41,7 +41,7 @@ Scenario #3 Mitigation
This scenario can be mitigated by ensuring Designate has been configured, and
is updated periodically, with the latest list of gTLD's published as the
`IANA TLD list`_. These TLDs can be entered into Designate through the
:doc:`TLD API </rest/v2/tlds>`.
`TLD API`_
Scenario #4 Mitigation
----------------------
@ -54,7 +54,7 @@ up to fill this gap, crowdsourcing the list of "public suffixes", which
includes both standard TLDs and public second level domains. We recommend
configuring, and periodically updating, Designate with Mozilla's
`Public Suffix list`_. These public suffixes can be entered into Designate
through the :doc:`TLD API </rest/v2/tlds>`.
through the `TLD API`_
DNS Cache Poisoning
===================
@ -107,3 +107,4 @@ In the main PowerDNS configuration file, include the following statement::
.. _IANA TLD list: https://data.iana.org/TLD/tlds-alpha-by-domain.txt
.. _Public Suffix list: https://publicsuffix.org/
.. _Bug 1471159: https://bugs.launchpad.net/designate/+bug/1471159
.. _TLD API: http://developer.openstack.org/api-ref/dns/#tld

17
doc/source/rest.rst
View File

@ -81,20 +81,9 @@ V1 API
V2 API
------
.. toctree::
:maxdepth: 2
:glob:
rest/v2/collections
rest/v2/zones
rest/v2/recordsets
rest/v2/tlds
rest/v2/blacklists
rest/v2/pools
rest/v2/limits
rest/v2/reverse
rest/v2/service_status
rest/v2/tsigkeys
The V2 API is documented on the OpenStack Developer `api site`_
Admin API
---------
@ -103,3 +92,5 @@ Admin API
:glob:
rest/admin/quotas
.. _api site: http://developer.openstack.org/api-ref/dns/

284
doc/source/rest/v2/blacklists.rst
View File

@ -1,284 +0,0 @@
..
Copyright (c) 2014 Rackspace Hosting
All Rights Reserved.
Author: Betsy Luzader <betsy.luzader@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.
Blacklists
==========
Overview
-------------------
The blacklist entries are used to manage blacklisted zones. If a zone is blacklisted, then it cannot be used to
create a zone. By default, only an admin can manage these entries. Blacklisted zones are stored as a regular expression
(regex) pattern in the :ref:`database` in the *blacklists* table.
Blacklist Checks
-------------------
Every time a new zone is created, that domain name is checked against the blacklisted zones in the database.
If it matches the regex pattern, then a 400 is returned with the message "Blacklisted domain name". If there
is no match, then the zone is created. When a new blacklisted pattern is added, it will catch any matching
new zones, but it does not check for existing zones that match the blacklisted pattern.
Regular Expressions
-------------------
Any valid regular expression may be added to the blacklists table. Here are some examples:
#. ``^example\\.com\\.$``
This will block the "example.com." domain, but will not block any sub-domains, e.g. "my.example.com." or anything
else containing example.com, such as, "myexample.com."
#. ``^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$``
This will block "example.com." and all sub-domains, e.g. "my.example.com.", but anything else containing
example.com, will not be blocked, such as, "myexample.com."
*NOTE:* When using regular expressions in json, the '\\' character needs to be escaped with an additional '\\', so it
needs to be written as "^example\\\\.com\\\\.$"
Create a Blacklist
------------------
.. http:post:: /blacklists
Create a blacklist. *pattern* is the only entry that is required. The domain name part of the pattern
should end in a period (.).'
**Example request**:
.. sourcecode:: http
POST /blacklists HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"pattern" : "^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
"description" : "This is a blacklisted domain."
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Location: 127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd
{
"description":"This is a blacklisted domain.",
"links":{
"self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd"
},
"pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
"created_at":"2014-03-11T21:54:57.000000",
"updated_at":null,
"id":"c47229fb-0831-4b55-a5b5-380d361be4bd"
}
:form created_at: timestamp
:form updated_at: timestamp
:form pattern: blacklist regular expression
:form id: uuid
:form description: UTF-8 text field
:form links: links to traverse the list
:statuscode 201: Created
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 409: Duplicate Blacklist
Get a Blacklist
---------------
.. http:get:: /blacklists/(uuid:id)
Lists a particular Blacklisted domain
**Example request**:
.. sourcecode:: http
GET /blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1
Host: example.com
Accept: application/json
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"description":"This is a blacklisted domain.",
"links":{
"self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd"
},
"pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
"created_at":"2014-03-11T21:54:57.000000",
"updated_at":null,
"id":"c47229fb-0831-4b55-a5b5-380d361be4bd"
}
:form created_at: timestamp
:form updated_at: timestamp
:form pattern: blacklist regular expression
:form id: uuid
:form description: UTF-8 text field
:form links: links to traverse the list
:statuscode 200: OK
:statuscode 401: Access Denied
:statuscode 404: Blacklist not found
List Blacklists
---------------
.. http:get:: /blacklists
Lists all blacklists
**Example request**:
.. sourcecode:: http
GET /blacklists HTTP/1.1
Host: example.com
Accept: application/json
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"blacklists":[
{
"description": "This is a blacklisted domain.",
"links":{
"self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd"
},
"pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
"created_at":"2014-03-11T21:54:57.000000",
"updated_at":null,
"id":"c47229fb-0831-4b55-a5b5-380d361be4bd"
},
{
"description": null,
"links":{
"self":"http://127.0.0.1:9001/v2/blacklists/61140aff-e2c8-488b-9bf4-da710ec8732b"
},
"pattern" : "^examples\\.com\\.$",
"created_at":"2014-03-07T21:05:59.000000",
"updated_at":null,
"id":"61140aff-e2c8-488b-9bf4-da710ec8732b"
}
],
"links":{
"self":"http://127.0.0.1:9001/v2/blacklists"
}
}
:form created_at: timestamp
:form updated_at: timestamp
:form pattern: blacklist regular expression
:form id: uuid
:form description: UTF-8 text field
:form links: links to traverse the list
:statuscode 200: OK
:statuscode 401: Access Denied
Update a Blacklist
------------------
.. http:patch:: /blacklists/(uuid:id)
updates a blacklist
**Example request**:
.. sourcecode:: http
PATCH blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"pattern" : "^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$",
"description" : "Updated the description"
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"description":"Updated the pattern to catch subdomains",
"links":{
"self":"http://127.0.0.1:9001/v2/blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd"
},
"created_at":"2014-03-11T21:54:57.000000",
"updated_at":"2014-03-13T16:49:32.117187",
"id":"c47229fb-0831-4b55-a5b5-380d361be4bd",
"pattern":"^([A-Za-z0-9_\\-]+\\.)*example\\.com\\.$"
}
:form created_at: timestamp
:form updated_at: timestamp
:form pattern: blacklist regular expression pattern
:form id: uuid
:form description: UTF-8 text field
:form links: links to traverse the list
:statuscode 200: OK
:statuscode 401: Access Denied
:statuscode 404: Blacklist not found
:statuscode 409: Duplicate Blacklist
Delete a Blacklist
------------------
.. http:delete:: /blacklists/(uuid:id)
delete a blacklist
**Example request**:
.. sourcecode:: http
DELETE /blacklists/c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1
Host: example.com
**Example response**:
.. sourcecode:: http
HTTP/1.1 204 No Content
Content-Type: application/json; charset=UTF-8
Content-Length: 0
:statuscode 204: No Content
:statuscode 401: Access Denied
:statuscode 404: Blacklist not found

544
doc/source/rest/v2/collections.rst
View File

@ -1,544 +0,0 @@
..
Copyright 2014 Rackspace Hosting
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.
..
Collections
===========
The following conventions apply to all collections, unless otherwise noted below.
Links
-----
A links object will exist at the root of all Collection responses.
At the minimum, it will contain a "self" link. If the collection
resultset is not complete, a "next" link will be included for
pagination.
**Request:**
.. sourcecode:: http
GET /v2/zones?limit=2 HTTP/1.1
Host: dns.provider.com
Accept: application/json
**Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"zones": [{
"status": "ACTIVE",
"masters": [],
"name": "example1.org.",
"links": {
"self": "http://dns.provider.com:9001/v2/zones/bd1b954e-69cd-4a91-99b4-0bcc08533123"
},
"transferred_at": null,
"created_at": "2016-03-14T05:41:49.000000",
"pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842",
"updated_at": "2016-03-14T07:33:49.000000",
"version": 10,
"id": "bd1b954e-69cd-4a91-99b4-0bcc08533123",
"ttl": 3600,
"action": "NONE",
"attributes": {},
"serial": 1457940809,
"project_id": "54c3cc0b8e21491f820fc701b83cb7fb",
"type": "PRIMARY",
"email": "hostmaster@example.com",
"description": null
},
{ "status": "ACTIVE",
"masters": [],
"name": "example.com.",
"links": {
"self": "http://dns.provider.com:9001/v2/zones/45fd892d-7a67-4f65-9df0-87273f228d6c"
},
"transferred_at": null,
"created_at": "2016-03-14T07:50:38.000000",
"pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842",
"updated_at": "2016-03-14T07:50:43.000000",
"version": 2,
"id": "45fd892d-7a67-4f65-9df0-87273f228d6c",
"ttl": 3600,
"action": "NONE",
"attributes": {},
"serial": 1457941838,
"project_id": "54c3cc0b8e21491f820fc701b83cb7fb",
"type": "PRIMARY",
"email": "hostmaster@example.com",
"description": null
}],
"links": {
"self": "http://dns.provider.com:9001/v2/zones?limit=2",
"next": "http://dns.provider.com:9001/v2/zones?limit=2&marker=45fd892d-7a67-4f65-9df0-87273f228d6c"
},
"metadata": {
"total_count": 2
}
}
Pagination and Sorting
----------------------
Pagination is available on all collections and is controlled
using a combination of four optional query parameters:
* `marker` - denotes the ID of the last item in the previous list.
* `limit` - use to set the maximum number of items per page, use
"max" to return the upper limit of results as defined
by the operator. If not supplied, the default per page
limit as defined by the operator will be used.
* `sort_key` - sorts the results by the specified attribute
* By default, elements will be sorted by their creation date.
* `sort_dir` - determines whether sorted results are displayed in
ascending or descending order.
* If explicitly used, the value of sort_dir must be either
'asc' or 'desc'. Otherwise, the default is 'asc'.
To navigate the collection, the parameters limit and marker can be
set in the URI (e.g.?limit=100&marker=<UUID>). Items are sorted, as
a default, by create time in ascending order.
Collection responses will include a `links` object containing absolute
URLs for the current and next page. These links may be omitted, or
null, at the edges of a paginated collection.
The following example takes a collection of zones and sorts it in
descending order, using ID as the sort key rather than creation date.
**Request:**
.. sourcecode:: http
GET /v2/zones?sort_key=id&sort_dir=desc HTTP/1.1
Host: dns.provider.com
Accept: application/json
**Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"zones": [{
"status": "ACTIVE",
"description": null,
"updated_at": null,
"ttl": 3600,
"serial": 1405435156,
"id": "c316def0-8599-4030-9dcd-2ce566348115",
"name": "abc.example.net.",
"created_at": "2014-07-15T14:39:16.000000",
"pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2",
"version": 1,
"project_id": "noauth-project",
"email": "hostmaster@example.net",
"links": {
"self": "http://dns.provider.com/v2/zones/c316def0-8599-4030-9dcd-2ce566348115"
}
},
{
"status": "ACTIVE",
"description": null,
"updated_at": "2014-07-08T20:28:31.000000",
"ttl": 86400,
"serial": 1404851315,
"id": "a4e29ed3-d7a4-4e4d-945d-ce64678d3b94",
"name": "example.com.",
"created_at": "2014-07-08T20:28:19.000000",
"pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2",
"version": 1,
"project_id": "noauth-project",
"email": "hostmaster@example.com",
"links": {
"self": "http://dns.provider.com/v2/zones/a4e29ed3-d7a4-4e4d-945d-ce64678d3b94"
}
},
{
"status": "ACTIVE",
"description": null,
"updated_at": null,
"ttl": 3600,
"serial": 1405435142,
"id": "38dbf635-45cb-4873-8300-6c273f0283c7",
"name": "example.org.",
"created_at": "2014-07-15T14:39:02.000000",
"pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2",
"version": 1,
"project_id": "noauth-project",
"email": "hostmaster@example.org",
"links": {
"self": "http://dns.provider.com/v2/zones/38dbf635-45cb-4873-8300-6c273f0283c7"
}
},
{
"status": "ACTIVE",
"description": null,
"updated_at": null,
"ttl": 3600,
"serial": 1405435099,
"id": "13db810b-917d-4898-bc28-4d4ee370d20d",
"name": "abc.example.com.",
"created_at": "2014-07-15T14:38:19.000000",
"pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2",
"version": 1,
"project_id": "noauth-project",
"email": "hostmaster@example.com",
"links": {
"self": "http://dns.provider.com/v2/zones/13db810b-917d-4898-bc28-4d4ee370d20d"
}
}],
"links": {
"self": "https://dns.provider.com/v2/zones?sort_key=id&sort_dir=desc"
}
}
This example takes the previously sorted list and displays only the middle two resources.
.. sourcecode:: http
GET /v2/zones?sort_key=id&sort_dir=desc&marker=c316def0-8599-4030-9dcd-2ce566348115&limit=2 HTTP/1.1
Host: dns.provider.com
Accept: application/json
**Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"zones": [{
"status": "ACTIVE",
"description": null,
"updated_at": "2014-07-08T20:28:31.000000",
"ttl": 86400,
"serial": 1404851315,
"id": "a4e29ed3-d7a4-4e4d-945d-ce64678d3b94",
"name": "example.com.",
"created_at": "2014-07-08T20:28:19.000000",
"pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2",
"version": 1,
"project_id": "noauth-project",
"email": "hostmaster@example.com",
"links": {
"self": "http://dns.provider.com/v2/zones/a4e29ed3-d7a4-4e4d-945d-ce64678d3b94"
}
},
{
"status": "ACTIVE",
"description": null,
"updated_at": null,
"ttl": 3600,
"serial": 1405435142,
"id": "38dbf635-45cb-4873-8300-6c273f0283c7",
"name": "example.org.",
"created_at": "2014-07-15T14:39:02.000000",
"pool_id": "572ba08c-d929-4c70-8e42-03824bb24ca2",
"version": 1,
"project_id": "noauth-project",
"email": "hostmaster@example.org",
"links": {
"self": "http://dns.provider.com/v2/zones/38dbf635-45cb-4873-8300-6c273f0283c7"
}
}],
"links": {
"self": "https://dns.provider.com/v2/zones?sort_key=id&sort_dir=desc&marker=c316def0-8599-4030-9dcd-2ce566348115&limit=2",
"next": "https://dns.provider.com/v2/zones?sort_key=id&sort_dir=desc&limit=2&marker=38dbf635-45cb-4873-8300-6c273f0283c7"
}
}
Filtering
---------
Filtering is available on all collections and is controlled using
query parameters which match the name of the attribute being filtered.
It is *not* required that all attributes are available as filter
targets, but the majority will be.
Currently, the following attributes support filtering:
* **Blacklists**: pattern
* **Recordsets**: name, type, ttl, data, description, status
* **TLDs**: name
* **Zones**: name, email, ttl, description, status
Filters can be an exact match search or a wildcard search. Currently,
wildcard search is supported using the '*' character.
The following example takes a collection of zones and filters it
by the "name" parameter.
**Request:**
.. sourcecode:: http
GET /v2/zones?name=example.com. HTTP/1.1
Host: dns.provider.com
Accept: application/json
**Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"zones": [{
"status": "ACTIVE",
"masters": [],
"name": "example.com.",
"links": {
"self": "http://dns.provider.com:9001/v2/zones/45fd892d-7a67-4f65-9df0-87273f228d6c"
},
"transferred_at": null,
"created_at": "2016-03-14T07:50:38.000000",
"pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842",
"updated_at": "2016-03-14T07:50:43.000000",
"version": 2,
"id": "45fd892d-7a67-4f65-9df0-87273f228d6c",
"ttl": 3600,
"action": "NONE",
"attributes": {},
"serial": 1457941838,
"project_id": "54c3cc0b8e21491f820fc701b83cb7fb",
"type": "PRIMARY",
"email": "hostmaster@example.com",
"description": null
}],
"links": {
"self": "http://dns.provider.com:9001/v2/zones?name=example.com."
},
"metadata": {
"total_count": 1
}
}
Wildcards can be placed anywhere within the query. The following example
demonstrates the use of wildcards on the right side of a query:
**Request:**
.. sourcecode:: http
GET /v2/zones?name=example* HTTP/1.1
Host: dns.provider.com
Accept: application/json
**Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"zones": [{
"status": "ACTIVE",
"masters": [],
"name": "example1.org.",
"links": {
"self": "http://dns.provider.com:9001/v2/zones/bd1b954e-69cd-4a91-99b4-0bcc08533123"
},
"transferred_at": null,
"created_at": "2016-03-14T05:41:49.000000",
"pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842",
"updated_at": "2016-03-14T07:33:49.000000",
"version": 10,
"id": "bd1b954e-69cd-4a91-99b4-0bcc08533123",
"ttl": 3600,
"action": "NONE",
"attributes": {},
"serial": 1457940809,
"project_id": "54c3cc0b8e21491f820fc701b83cb7fb",
"type": "PRIMARY",
"email": "hostmaster@example.com",
"description": null
},
{
"status": "ACTIVE",
"masters": [],
"name": "example.com.",
"links": {
"self": "http://dns.provider.com:9001/v2/zones/45fd892d-7a67-4f65-9df0-87273f228d6c"
},
"transferred_at": null,
"created_at": "2016-03-14T07:50:38.000000",
"pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842",
"updated_at": "2016-03-14T07:50:43.000000",
"version": 2,
"id": "45fd892d-7a67-4f65-9df0-87273f228d6c",
"ttl": 3600,
"action": "NONE",
"attributes": {},
"serial": 1457941838,
"project_id": "54c3cc0b8e21491f820fc701b83cb7fb",
"type": "PRIMARY",
"email": "hostmaster@example.com",
"description": null
}],
"links": {
"self": "http://dns.provider.com:9001/v2/zones?name=example%2A"
},
"metadata": {
"total_count": 2
}
}
This example demonstrates the use of multiple wildcards:
**Request:**
.. sourcecode:: http
GET /v2/zones?name=*example* HTTP/1.1
Host: dns.provider.com
Accept: application/json
**Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"zones": [{
"status": "ACTIVE",
"masters": [],
"name": "example.org.",
"links": {
"self": "http://dns.provider.com:9001/v2/zones/c991f02b-ae05-4570-bf75-73def68fe700"
},
"transferred_at": null,
"created_at": "2016-03-15T05:41:45.000000",
"pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842",
"updated_at": "2016-03-15T05:41:50.000000",
"version": 2,
"id": "c991f02b-ae05-4570-bf75-73def68fe700",
"ttl": 3600,
"action": "NONE",
"attributes": {},
"serial": 1458020505,
"project_id": "6b89012cdb2640c3a80b8d777d9bac16",
"type": "PRIMARY",
"email": "hostmaster@example.com",
"description": null
},
{
"status": "ACTIVE",
"masters": [],
"name": "example1.org.",
"links": {
"self": "http://dns.provider.com:9001/v2/zones/0d35ce4e-f3b4-4ba7-9b94-4f9eba49018a"
},
"transferred_at": null,
"created_at": "2016-03-15T05:54:24.000000",
"pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842",
"updated_at": "2016-03-15T05:54:44.000000",
"version": 2,
"id": "0d35ce4e-f3b4-4ba7-9b94-4f9eba49018a",
"ttl": 3600,
"action": "NONE",
"attributes": {},
"serial": 1458021264,
"project_id": "6b89012cdb2640c3a80b8d777d9bac16",
"type": "PRIMARY",
"email": "hostmaster@example.com",
"description": null
},
{
"status": "ACTIVE",
"masters": [],
"name": "example.com.",
"links": {
"self": "http://dns.provider.com:9001/v2/zones/a18eed67-806f-418c-883c-b7a8001a9fb6"
},
"transferred_at": null,
"created_at": "2016-03-15T06:51:47.000000",
"pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842",
"updated_at": "2016-03-15T06:51:52.000000",
"version": 2,
"id": "a18eed67-806f-418c-883c-b7a8001a9fb6",
"ttl": 3600,
"action": "NONE",
"attributes": {},
"serial": 1458024707,
"project_id": "6b89012cdb2640c3a80b8d777d9bac16",
"type": "PRIMARY",
"email": "hostmaster@example.com",
"description": null
},
{
"status": "ACTIVE",
"masters": [],
"name": "abc.example.org.",
"links": {
"self": "http://dns.provider.com:9001/v2/zones/c3cf2487-6c3e-44cd-a305-d52ccb7aaebd"
},
"transferred_at": null,
"created_at": "2016-03-15T06:53:13.000000",
"pool_id": "794ccc2c-d751-44fe-b57f-8894c9f5c842",
"updated_at": "2016-03-15T06:53:18.000000",
"version": 2,
"id": "c3cf2487-6c3e-44cd-a305-d52ccb7aaebd",
"ttl": 3600,
"action": "NONE",
"attributes": {},
"serial": 1458024793,
"project_id": "6b89012cdb2640c3a80b8d777d9bac16",
"type": "PRIMARY",
"email": "hostmaster@example.com",
"description": null
}],
"links": {
"self": "http://dns.provider.com:9001/v2/zones?name=%2Aexample%2A"
},
"metadata": {
"total_count": 4
}
}
Nested Collections
------------------
A nested collection is a collection without a URI of it's own.
The only current example we have of this is the "records" array
under the RecordSet resource.
By default, Nested Collections shall not be included in the
listing of it's parent resource. For example, List RecordSets
shall not include the "records" collection for each of the
RecordSets returned.

67
doc/source/rest/v2/limits.rst
View File

@ -1,67 +0,0 @@
..
Copyright 2015 Hewlett-Packard Development Company, L.P.
All Rights Reserved.
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.
Limits
======
Overview
-------------------
This endpoint is used to retrieve current limits.
Get Limits
----------
.. http:get:: /limits
Lists current limits
**Example request**:
.. sourcecode:: http
GET /limits HTTP/1.1
Host: example.com
Accept: application/json
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"max_page_limit": 1000,
"max_recordset_name_length": 255,
"max_recordset_records": 20,
"max_zone_name_length": 255,
"max_zone_records": 500,
"max_zone_recordsets": 500,
"max_zones": 10,
"min_ttl": null
}
:form max_page_limit: Max limit for paging
:form max_recordset_name_length: Max length for a RecordSet name
:form max_recordset_records: Max number RecordSet of Records
:form max_zone_name_length: Max length for a Zone name
:form max_zone_records: Max number of Records in a Zone
:form max_zone_recordsets: Max number of RecordSets in a Zone
:form max_zones: Max number of Zones
:form max_ttl: Max TTL
:statuscode 200: OK

329
doc/source/rest/v2/pools.rst
View File

@ -1,329 +0,0 @@
..
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
{
"name": "Example Pool",
"ns_records": [
{
"hostname": "ns1.example.org.",
"priority": 1
}
]
}
**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
{
"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 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 ns_records: a list of ns_records 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,
"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
}
]
}
: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
{
"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"
}
: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
{
"ns_records": [
{
"hostname": "ns1.example.org.",
"priority": 1
},
{
"hostname": "ns3.example.org.",
"priority": 2
}
],
}
**Example response**:
.. code-block:: http
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
.. code-block:: json
{
"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.
: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

805
doc/source/rest/v2/recordsets.rst
View File

@ -1,805 +0,0 @@
..
Copyright (C) 2014 Rackspace
Author: Joe McBride <jmcbride@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.
Record Sets and Records
=======================
A record set groups together a list of related records. It is the essential content of your zone file and is used to define the various domain to server routes for your application. Record sets are also referred to as "Resource Record Sets" or "RRSet".
The following illustrates a record set in the BIND file format:
.. sourcecode:: none
example.org. 86400 MX 10 mail1.example.org.
20 mail2.example.org.
30 mail3.example.org.
.. note:: The "description" field on Records cannot be accessed from the V2
API. Likewise, the "description" field on Record Sets cannot be accessed
from the V1 API.
Create Record Set (A, AAAA, CNAME, NS, and TXT)
-----------------------------------------------
The following format can be used for common record set types including A, AAAA, CNAME, NS and TXT. Simply replace the type and records with the respective values. NS record sets can only be created and deleted. Examples for MX, SSHFP, SPF and SRV will follow.
.. http:post:: /zones/(uuid:id)/recordsets
Creates a new record set.
**Example request:**
.. sourcecode:: http
POST /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
{
"name" : "example.org.",
"description" : "This is an example record set.",
"type" : "A",
"ttl" : 3600,
"records" : [
"10.1.0.2"
]
}
**Example response:**
.. sourcecode:: http
HTTP/1.1 201 Created
Content-Type: application/json
{
"description": "This is an example record set.",
"links": {
"self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648"
},
"updated_at": null,
"records": [
"10.1.0.2"
],
"ttl": 3600,
"id": "f7b10e9b-0cae-4a91-b162-562bc6096648",
"name": "example.org.",
"zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
"created_at": "2014-10-24T19:59:44.000000",
"version": 1,
"type": "A"
}
:form description: UTF-8 text field
:form name: domain name
:form ttl: time-to-live numeric value in seconds
:form type: type of record set
:form records: a list of record values
:statuscode 201: Created
:statuscode 202: Accepted
:statuscode 401: Access Denied
Get Record Set
--------------
Two APIs can be used to retrieve a single recordset. One with zone ID in url, the other without.
.. http:get:: /zones/(uuid:id)/recordsets/(uuid:id)
Retrieves a record set with the specified record set ID.
**Example request:**
.. sourcecode:: http
GET /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648 HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
**Example response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"description": "This is an example recordset.",
"links": {
"self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648"
},
"updated_at": null,
"records": [
"10.1.0.2"
],
"ttl": 3600,
"id": "f7b10e9b-0cae-4a91-b162-562bc6096648",
"name": "example.org.",
"zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
"created_at": "2014-10-24T19:59:44.000000",
"version": 1,
"type": "A"
}
:statuscode 200: Success
:statuscode 401: Access Denied
.. http:get:: /recordsets/(uuid:id)
If http client follows redirect, API returns a 200. Otherwise it returns 301 with the canonical location of the requested recordset.
**Example request:**
.. sourcecode:: http
GET /v2/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648 HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
**Example response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"description": "This is an example recordset.",
"links": {
"self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648"
},
"updated_at": null,
"records": [
"10.1.0.2"
],
"ttl": 3600,
"id": "f7b10e9b-0cae-4a91-b162-562bc6096648",
"name": "example.org.",
"zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
"created_at": "2014-10-24T19:59:44.000000",
"version": 1,
"type": "A"
}
:statuscode 301: Moved Permanently
:statuscode 200: Success
:statuscode 401: Access Denied
List Record Sets
----------------
**Lists all record sets for a given zone**
.. http:get:: /zones/(uuid:id)/recordsets
**Example Request:**
.. sourcecode:: http
GET /v2/zones/c991f02b-ae05-4570-bf75-73def68fe700/recordsets HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
**Example Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"recordsets": [
{
"status": "ACTIVE",
"description": null,
"links": {
"self": "http://127.0.0.1:9001/v2/zones/c991f02b-ae05-4570-bf75-73def68fe700/recordsets/29c5420e-8acb-4ef9-9aca-709a196c22dc"
},
"created_at": "2016-03-15T05:41:45.000000",
"updated_at": "2016-03-15T07:34:02.000000",
"records": [
"ns1.example.com. abc.example.com. 1458027242 3586 600 86400 3600"
],
"zone_id": "c991f02b-ae05-4570-bf75-73def68fe700",
"version": 2,
"ttl": null,
"action": "NONE",
"type": "SOA",
"id": "29c5420e-8acb-4ef9-9aca-709a196c22dc",
"name": "example.org."
},
{
"status": "ACTIVE",
"description": null,
"links": {
"self": "http://127.0.0.1:9001/v2/zones/c991f02b-ae05-4570-bf75-73def68fe700/recordsets/7d80c4c6-e416-41d3-a29b-f408b9f51b8e"
},
"created_at": "2016-03-15T05:41:45.000000",
"updated_at": null,
"records": [
"ns1.example.com."
],
"zone_id": "c991f02b-ae05-4570-bf75-73def68fe700",
"version": 1,
"ttl": null,
"action": "NONE",
"type": "NS",
"id": "7d80c4c6-e416-41d3-a29b-f408b9f51b8e",
"name": "example.org."
},
{
"status": "ACTIVE",
"description": "this is an example recordset",
"links": {
"self": "http://127.0.0.1:9001/v2/zones/c991f02b-ae05-4570-bf75-73def68fe700/recordsets/345e779d-90a4-4245-a460-42721a750e8c"
},
"created_at": "2016-03-15T07:34:02.000000",
"updated_at": null,
"records": ["10.1.0.2"],
"zone_id": "c991f02b-ae05-4570-bf75-73def68fe700",
"version": 1,
"ttl": null,
"action": "NONE",
"type": "A",
"id": "345e779d-90a4-4245-a460-42721a750e8c",
"name": "example.org."
}
],
"links": {
"self": "http://127.0.0.1:9001/v2/zones/c991f02b-ae05-4570-bf75-73def68fe700/recordsets"
},
"metadata": {
"total_count": 3
}
}
:statuscode 200: Success
:statuscode 401: Access Denied
**Lists record sets across all zones**
.. http:get:: /recordsets
**Example Request:**
.. sourcecode:: http
GET /v2/recordsets HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
**Example Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"recordsets": [
{
"description": null,
"links": {
"self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/65ee6b49-bb4c-4e52-9799-31330c94161f"
},
"updated_at": null,
"records": [
"ns1.devstack.org."
],
"action": "NONE",
"ttl": null,
"status": "ACTIVE",
"id": "65ee6b49-bb4c-4e52-9799-31330c94161f",
"name": "example.org.",
"zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
"zone_name": "example.org.",
"created_at": "2014-10-24T19:59:11.000000",
"version": 1,
"type": "NS"
},
{
"description": null,
"links": {
"self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/14500cf9-bdff-48f6-b06b-5fc7491ffd9e"
},
"updated_at": "2014-10-24T19:59:46.000000",
"records": [
"ns1.devstack.org. jli.ex.com. 1458666091 3502 600 86400 3600"
],
"action": "NONE",
"ttl": null,
"status": "ACTIVE",
"id": "14500cf9-bdff-48f6-b06b-5fc7491ffd9e",
"name": "example.org.",
"zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
"zone_name": "example.org.",
"created_at": "2014-10-24T19:59:12.000000",
"version": 1,
"type": "SOA"
},
{
"name": "example.com.",
"id": "12caacfd-f0fc-4bcb-aa24-c42769897822",
"type": "SOA",
"zone_name": "example.com.",
"action": "NONE",
"ttl": null,
"status": "ACTIVE",
"description": null,
"links": {
"self": "http://127.0.0.1:9001/v2/zones/b8d7eaf1-e5c7-4b15-be6e-4b2809f47ec3/recordsets/12caacfd-f0fc-4bcb-aa24-c42769897822"
},
"created_at": "2016-03-22T16:12:35.000000",
"updated_at": "2016-03-22T17:01:31.000000",
"records": [
"ns1.devstack.org. jli.ex.com. 1458666091 3502 600 86400 3600"
],
"zone_id": "b8d7eaf1-e5c7-4b15-be6e-4b2809f47ec3",
"version": 2
},
{
"name": "example.com.",
"id": "f39c51d1-ec2c-48a8-b9f7-877d56b7b82a",
"type": "NS",
"zone_name": "example.com.",
"action": "NONE",
"ttl": null,
"status": "ACTIVE",
"description": null,
"links": {
"self": "http://127.0.0.1:9001/v2/zones/b8d7eaf1-e5c7-4b15-be6e-4b2809f47ec3/recordsets/f39c51d1-ec2c-48a8-b9f7-877d56b7b82a"
},
"created_at": "2016-03-22T16:12:35.000000",
"updated_at": null,
"records": [
"ns1.devstack.org."
],
"zone_id": "b8d7eaf1-e5c7-4b15-be6e-4b2809f47ec3",
"version": 1
},
],
"metadata": {
"total_count": 4
},
"links": {
"self": "https://127.0.0.1:9001/v2/recordsets"
}
}
**Filtering record sets**
.. http:get:: /recordsets?KEY=VALUE
**Example Request:**
.. sourcecode:: http
GET /v2/recordsets?data=192.168* HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
**Example Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json
{
"metadata": {
"total_count": 2
},
"links": {
"self": "http://127.0.0.1:9001/v2/recordsets?data=192.168%2A"
},
"recordsets": [
{
"name": "mail.example.net.",
"id": "a48588c5-5093-4585-b0fc-3e399d169c01",
"type": "A",
"zone_name": "example.net.",
"action": "NONE",
"ttl": null,
"status": "ACTIVE",
"description": null,
"links": {
"self": "http://127.0.0.1:9001/v2/zones/601a25f0-5c4d-4058-8d9c-e6a78f5ffbb8/recordsets/a48588c5-5093-4585-b0fc-3e399d169c01"
},
"created_at": "2016-04-04T20:11:08.000000",
"updated_at": null,
"records": [
"192.168.0.1"
],
"zone_id": "601a25f0-5c4d-4058-8d9c-e6a78f5ffbb8",
"version": 1
},
{
"name": "www.example.net.",
"id": "f2c7a0f6-8ec7-4d14-b8ec-2a55a8129160",
"type": "A",
"zone_name": "example.net.",
"action": "NONE",
"ttl": null,
"status": "ACTIVE",
"description": null,
"links": {
"self": "http://127.0.0.1:9001/v2/zones/601a25f0-5c4d-4058-8d9c-e6a78f5ffbb8/recordsets/f2c7a0f6-8ec7-4d14-b8ec-2a55a8129160"
},
"created_at": "2016-04-04T22:21:03.000000",
"updated_at": null,
"records": [
"192.168.6.6"
],
"zone_id": "601a25f0-5c4d-4058-8d9c-e6a78f5ffbb8",
"version": 1
}
]
}
Update Record Set
-----------------
.. http:put:: /zones/(uuid:id)/recordsets/(uuid:id)
Replaces the record set with the specified details.
In the example below, we update the TTL to 3600.
**Request:**
.. sourcecode:: http
PUT /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648 HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
{
"description" : "I updated this example.",
"ttl" : 60,
"records" : [
"10.1.0.2"
]
}
**Response:**
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
{
"description": "I updated this example.",
"ttl": 60,
"records": [
"10.1.0.2"
],
"links": {
"self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648"
},
"updated_at": "2014-10-24T20:15:27.000000",
"id": "f7b10e9b-0cae-4a91-b162-562bc6096648",
"name": "example.org.",
"zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
"created_at": "2014-10-24T19:59:44.000000",
"version": 2,
"type": "A"
}
:form description: UTF-8 text field
:form name: domain name
:form ttl: time-to-live numeric value in seconds
:form type: type of record set (can not be changed on update)
:form records: a list of data records
:statuscode 200: Success
:statuscode 202: Accepted
:statuscode 401: Access Denied
Delete Record Set
-----------------
.. http:delete:: zones/(uuid:id)/recordsets/(uuid:id)
Deletes a record set with the specified record set ID.
**Example Request:**
.. sourcecode:: http
DELETE /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096648 HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
**Example Response:**
.. sourcecode:: http
HTTP/1.1 202 Accepted
:statuscode: 202 Accepted
Create MX Record Set
--------------------
.. http:post:: /zones/(uuid:id)/recordsets
Creates a new MX record set. MX record set data format is "<priority> <host>" (e.g. "10 10.1.0.1").
**Example request:**
.. sourcecode:: http
POST /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
{
"name" : "mail.example.org.",
"description" : "An MX recordset.",
"type" : "MX",
"ttl" : 3600,
"records" : [
"10 mail1.example.org.",
"20 mail2.example.org.",
"30 mail3.example.org.",
"40 mail4.example.org."
]
}
**Example response:**
.. sourcecode:: http
HTTP/1.1 201 Created
Content-Type: application/json
{
"description": "An MX recordset.",
"links": {
"self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096649"
},
"updated_at": null,
"records" : [
"10 mail1.example.org.",
"20 mail2.example.org.",
"30 mail3.example.org.",
"40 mail4.example.org."
],
"ttl": 3600,
"id": "f7b10e9b-0cae-4a91-b162-562bc6096649",
"name": "mail.example.org.",
"zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
"created_at": "2014-10-25T19:59:44.000000",
"version": 1,
"type": "MX"
}
:form description: UTF-8 text field
:form name: domain name
:form ttl: time-to-live numeric value in seconds
:form type: type of record set
:form records: a list of record values
:statuscode 201: Created
:statuscode 401: Access Denied
Create SSHFP Record Set
-----------------------
.. http:post:: /zones/(uuid:id)/recordsets
Creates a new SSHFP record set. SSHFP record set data format is "<algorithm> <fingerprint-type> <fingerprint-hex>" (e.g. "1 2 aa2df857dc65c5359f02ca75ec5c4308c0100594d931e8d243a42f586257b5e8").
**Example request:**
.. sourcecode:: http
POST /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
{
"name" : "foo.example.org.",
"description" : "An SSHFP recordset.",
"type" : "SSHFP",
"ttl" : 3600,
"records" : [
"1 2 aa2df857dc65c5359f02ca75ec5c4308c0100594d931e8d243a42f586257b5e8"
]
}
**Example response:**
.. sourcecode:: http
HTTP/1.1 201 Created
Content-Type: application/json
{
"description": "An SSHFP recordset.",
"links": {
"self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096650"
},
"updated_at": null,
"records" : [
"1 2 aa2df857dc65c5359f02ca75ec5c4308c0100594d931e8d243a42f586257b5e8"
],
"ttl": 3600,
"id": "f7b10e9b-0cae-4a91-b162-562bc6096650",
"name": "foo.example.org.",
"zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
"created_at": "2014-11-10T19:59:44.000000",
"version": 1,
"type": "SSHFP"
}
:form description: UTF-8 text field
:form name: domain name
:form ttl: time-to-live numeric value in seconds
:form type: type of record set
:form records: a list of record values
:statuscode 201: Created
:statuscode 401: Access Denied
Create SPF Record Set
---------------------
.. http:post:: /zones/(uuid:id)/recordsets
Creates a new SPF record set. SPF record set data formatting follows standard SPF record syntax.
**Example request:**
.. sourcecode:: http
POST /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
{
"name" : "foospf.example.org.",
"description" : "An SPF recordset.",
"type" : "SPF",
"ttl" : 3600,
"records" : [
"v=spf1 +all"
]
}
**Example response:**
.. sourcecode:: http
HTTP/1.1 201 Created
Content-Type: application/json
{
"description": "An SPF recordset.",
"links": {
"self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096651"
},
"updated_at": null,
"records" : [
"v=spf1 +all"
],
"ttl": 3600,
"id": "f7b10e9b-0cae-4a91-b162-562bc6096651",
"name": "foospf.example.org.",
"zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
"created_at": "2014-11-10T19:59:44.000000",
"version": 1,
"type": "SPF"
}
:form description: UTF-8 text field
:form name: domain name
:form ttl: time-to-live numeric value in seconds
:form type: type of record set
:form records: a list of record values
:statuscode 201: Created
:statuscode 401: Access Denied
Create SRV Record Set
---------------------
.. http:post:: /zones/(uuid:id)/recordsets
Creates a new SRV record set. SRV record set data format is "<priority> <weight> <port> <target-hostname>" (e.g. "10 0 5060 server1.example.org."). The "name" attribute should contain the service name, protocol and domain name (e.g. "_sip.tcp.example.org.").
**Example request:**
.. sourcecode:: http
POST /v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
{
"name" : "_sip.tcp.example.org.",
"description" : "An SRV recordset.",
"type" : "SRV",
"ttl" : 3600,
"records" : [
"10 0 5060 server1.example.org."
]
}
**Example response:**
.. sourcecode:: http
HTTP/1.1 201 Created
Content-Type: application/json
{
"description": "An SRV recordset.",
"links": {
"self": "https://127.0.0.1:9001/v2/zones/2150b1bf-dee2-4221-9d85-11f7886fb15f/recordsets/f7b10e9b-0cae-4a91-b162-562bc6096652"
},
"updated_at": null,
"records" : [
"10 0 5060 server1.example.org."
],
"ttl": 3600,
"id": "f7b10e9b-0cae-4a91-b162-562bc6096652",
"name": "_sip.tcp.example.org.",
"zone_id": "2150b1bf-dee2-4221-9d85-11f7886fb15f",
"created_at": "2014-11-10T19:59:44.000000",
"version": 1,
"type": "SRV"
}
:form description: UTF-8 text field
:form name: domain name
:form ttl: time-to-live numeric value in seconds
:form type: type of record set
:form records: a list of record values
:statuscode 201: Created
:statuscode 401: Access Denied

236
doc/source/rest/v2/reverse.rst
View File

@ -1,236 +0,0 @@
..
Copyright 2015 Hewlett-Packard Development Company, L.P.
All Rights Reserved.
Author: Endre Karlson <endre.karlson@hpe.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.
.. note:
Currently the /reverse endpoint is used to tie reverse DNS records to IPs.
FloatingIPs
===========
In order to use the FloatingIPs functionality you will need to have a FloatingIP
associated to your project in Neutron.
Set FloatingIP's PTR record
----------------------------
.. http:patch:: /reverse/floatingips/(string:region):(uuid:floatingip_id)
Set a PTR record for the given FloatingIP. The domain if it does not exist
will be provisioned automatically.
**Example request**:
.. sourcecode:: http
POST /reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"ptrdname" : "smtp.example.com.",
"description" : "This is a floating ip for 10.0.0.1",
"ttl": 600
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 202 Created
Content-Type: application/json; charset=UTF-8
Location: http://example.com:9001/v2/reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd
{
"ptrdname": "smtp.example.com.",
"ttl": 600,
"description":"This is a floating ip for 172.24.4.3",
"address": "172.24.4.3",
"action": "CREATE",
"status": "PENDING",
"links":{
"self":"http://example.com:9001/v2/reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd"
},
"pattern":"smtp.example.com.",
"created_at":"2014-03-11T21:54:57.000000",
"updated_at":null,
"id":"RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd",
}
:form created_at: timestamp
:form updated_at: timestamp
:form ptrdname: Hostname
:form ttl: Time to live
:form address: The FloatingIP address
:form id: A combination of the Region and FloatingIP ID
:form description: UTF-8 text field
:form links: links to traverse the list
:form action: Provisioning Action
:form status: Provisioning Status
:statuscode 202: Created
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 404: FloatingIP / PTR Not found
Get a FloatingIP's PTR record
-----------------------------
.. http:get:: /reverse/floatingips/(string:region):(uuid:floatingip_id)
Shows a particular FloatingIP PTR
**Example request**:
.. sourcecode:: http
GET /reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1
Host: example.com
Accept: application/json
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"ptrdname": "smtp.example.com.",
"ttl": 600,
"description":"This is a floating ip for 172.24.4.3",
"address": "172.24.4.3",
"action": "NONE",
"status": "ACTIVE",
"links":{
"self":"http://example.com:9001/v2/reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd"
},
"pattern":"smtp.example.com.",
"created_at":"2014-03-11T21:54:57.000000",
"updated_at":null,
"id":"RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd",
}
:form created_at: timestamp
:form updated_at: timestamp
:form ptrdname: Hostname
:form ttl: Time to live
:form address: The FloatingIP address
:form id: A combination of the Region and FloatingIP ID
:form description: UTF-8 text field
:form links: links to traverse the list
:form action: Provisioning Action
:form status: Provisioning Status
:statuscode 200: OK
:statuscode 404: FloatingIP or PTR not found not found
List FloatingIP PTR records
---------------------------
.. http:get:: /reverse/floatingips/
Lists all FloatingIPs PTR records
**Example request**:
.. sourcecode:: http
GET /reverse/floatingips/ HTTP/1.1
Host: example.com
Accept: application/json
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"floatingips":[
{
"ttl": 600,
"ptrdname": "smtp.example.com.",
"description":"This is a floating ip for 172.24.4.3",
"address": "172.24.4.3",
"action": "NONE",
"status": "ACTIVE",
"links":{
"self":"http://example.com:9001/v2/reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd"
},
"pattern":"smtp.example.com.",
"created_at":"2014-03-11T21:54:57.000000",
"updated_at":null,
"id":"RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd",
},
{
"ptrdname": "www.example.com.",
"ttl": 600,
"description":"This is a floating ip for 172.24.4.4",
"address": "172.24.4.4",
"action": "NONE",
"status": "ACTIVE",
"links":{
"self":"http://example.com:9001/v2/reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4be"
},
"pattern":"smtp.example.com.",
"created_at":"2014-03-11T21:54:57.000000",
"updated_at":null,
"id":"RegionOne:c47229fb-0831-4b55-a5b5-380d361be4be",
}
],
"links":{
"self":"http://127.0.0.1:9001/v2/tlds"
}
}
:form created_at: timestamp
:form updated_at: timestamp
:form name: tld name
:form id: uuid
:form description: UTF-8 text field
:form links: links to traverse the list
:statuscode 200: OK
:statuscode 401: Access Denied
Unset the PTR record for a FloatingIP
-------------------------------------
.. http:patch:: /reverse/floatingips/(string:region):(uuid:floatingip_id)
Unset a PTR record for the given FloatingIP.
**Example request**:
.. sourcecode:: http
PATCH /reverse/floatingips/RegionOne:c47229fb-0831-4b55-a5b5-380d361be4bd HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"ptrdname" : null,
}
:statuscode 202: Pending
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 404: FloatingIP / PTR Not found

149
doc/source/rest/v2/service_status.rst
View File

@ -1,149 +0,0 @@
..
Copyright 2016 Hewlett Packard Enterprise Development Company LP
All Rights Reserved.
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.
Service Statuses
================
Overview
-----------------------
The Service Status entries are used to track the health state of the services
in the Designate system.
Get a Service Status
--------------------
.. http:get:: /service_statuses/(uuid:id)
Lists a particular Service Status
**Example request**:
.. sourcecode:: http
GET /service_statuses/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 HTTP/1.1
Host: example.com
Accept: application/json
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"capabilities": {},
"created_at": "2016-03-08T09:20:23.000000",
"heartbeated_at": "2016-03-08T09:26:18.000000",
"hostname": "vagrant-ubuntu-trusty-64",
"id": "769e8ca2-f71e-48be-8dee-631492c91e41",
"links": {
"self": "http://192.168.27.100:9001/v2/service_statuses/769e8ca2-f71e-48be-8dee-631492c91e41",
"service_status": "http://192.168.27.100:9001/v2/service_statuses/769e8ca2-f71e-48be-8dee-631492c91e41"
},
"service_name": "pool_manager",
"stats": {},
"status": "UP",
"updated_at": "2016-03-08T09:26:18.000000"
}
:form created_at: timestamp
:form updated_at: timestamp
:form id: uuid
:form description: UTF-8 text field
:form links: links to traverse the list
:form service_name: Service name
:form hostname: Service hostname
:form capabilities: Service capabilities - dict of capabilities
:form stats: Service stats - dict of stats
:form status: Service status - UP, DOWN or WARNING
:statuscode 200: OK
:statuscode 401: Access Denied
:statuscode 404: Service Status not found
List Service Statuses
---------------------
.. http:get:: /service_statuses
Lists all Service Statuses
**Example request**:
.. sourcecode:: http
GET /service_statuses HTTP/1.1
Host: example.com
Accept: application/json
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"service_statuses":[
{
"capabilities": {},
"created_at": "2016-03-08T09:20:23.000000",
"heartbeated_at": "2016-03-08T09:26:18.000000",
"hostname": "vagrant-ubuntu-trusty-64",
"id": "769e8ca2-f71e-48be-8dee-631492c91e41",
"links": {
"self": "http://192.168.27.100:9001/v2/service_statuses/769e8ca2-f71e-48be-8dee-631492c91e41",
"service_status": "http://192.168.27.100:9001/v2/service_statuses/769e8ca2-f71e-48be-8dee-631492c91e41"
},
"service_name": "pool_manager",
"stats": {},
"status": "UP",
"updated_at": "2016-03-08T09:26:18.000000"
},
{
"capabilities": {},
"created_at": "2016-03-08T09:20:26.000000",
"heartbeated_at": "2016-03-08T09:26:16.000000",
"hostname": "vagrant-ubuntu-trusty-64",
"id": "adcf580b-ea1c-4ebc-8a95-37ccdeed11ae",
"links": {
"self": "http://192.168.27.100:9001/v2/service_statuses/adcf580b-ea1c-4ebc-8a95-37ccdeed11ae",
"service_status": "http://192.168.27.100:9001/v2/service_statuses/adcf580b-ea1c-4ebc-8a95-37ccdeed11ae"
},
"service_name": "zone_manager",
"stats": {},
"status": "UP",
"updated_at": "2016-03-08T09:26:17.000000"
}
],
"links":{
"self":"http://127.0.0.1:9001/v2/service_statuses"
}
}
:form created_at: timestamp
:form updated_at: timestamp
:form id: uuid
:form description: UTF-8 text field
:form links: links to traverse the list
:form service_name: Service name
:form hostname: Service hostname
:form capabilities: Service capabilities - dict of capabilities
:form stats: Service stats - dict of stats
:form status: Service status - UP, DOWN or WARNING
:statuscode 200: OK
:statuscode 401: Access Denied

269
doc/source/rest/v2/tlds.rst
View File

@ -1,269 +0,0 @@
..
Copyright (c) 2014 Rackspace Hosting
All Rights Reserved.
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.
Tlds
=======
Overview
-----------------------
Tld (Top level domain) entries are used to manage the Tlds that Designate recognizes.
By default, only an admin can manage these entries. The Tlds are stored in the :ref:`database`
in the table *tlds* and are not propagated to the :ref:`dns-backend`. By default when
Designate starts up there are no Tlds in the database.
Tld Checks
-----------------------
When there are no Tld entries in the database, Tld checks are not enforced and
any domain/zone name can be created, as long as it adheres to the domain name schema.
When there are Tlds present in the database, then when a domain/zone is created
the name has to pass the following checks.
#. The last label in the domain/zone name must be present as a Tld entry in the database.
e.g. If a domain/zone with the name *example.com.* is being created then the entry *com* must be present in the database.
#. The domain/zone name must not be present as a Tld entry in the database.
e.g. If there is a Tld entry *co.uk* in the database, then a domain/zone with the name *co.uk.* cannot be created.
Create Tld
-------------
.. http:post:: /tlds
Create a tld. *name* is the only entry that is required. The *name* should
not end in a period (.).
**Example request**:
.. sourcecode:: http
POST /tlds HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"name" : "com",
"description" : "Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt"
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 201 Created
Content-Type: application/json; charset=UTF-8
Location: http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9
{
"description":"Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt",
"links":{
"self":"http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9"
},
"created_at":"2014-01-23T18:39:26.710827",
"updated_at":null,
"id":"5abe514c-9fb5-41e8-ab73-5ed25f8a73e9",
"name":"com"
}
:form created_at: timestamp
:form updated_at: timestamp
:form name: tld name
:form id: uuid
:form description: UTF-8 text field
:form links: links to traverse the list
:statuscode 201: Created
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 409: Duplicate Tld
Get a Tld
-------------
.. http:get:: /tlds/(uuid:id)
Lists a particular Tld
**Example request**:
.. sourcecode:: http
GET /tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 HTTP/1.1
Host: example.com
Accept: application/json
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"description":"Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt",
"links":{
"self":"http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9"
},
"created_at":"2014-01-23T18:39:26.710827",
"updated_at":null,
"id":"5abe514c-9fb5-41e8-ab73-5ed25f8a73e9",
"name":"com"
}
:form created_at: timestamp
:form updated_at: timestamp
:form name: tld name
:form id: uuid
:form description: UTF-8 text field
:form links: links to traverse the list
:statuscode 200: OK
:statuscode 401: Access Denied
:statuscode 404: Tld not found
List Tlds
------------
.. http:get:: /tlds
Lists all tlds
**Example request**:
.. sourcecode:: http
GET /tlds HTTP/1.1
Host: example.com
Accept: application/json
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"tlds":[
{
"description":"Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt",
"links":{
"self":"http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9"
},
"created_at":"2014-01-23T18:39:26.710827",
"updated_at":null,
"id":"5abe514c-9fb5-41e8-ab73-5ed25f8a73e9",
"name":"com"
},
{
"description":"Tld source http://data.iana.org/TLD/tlds-alpha-by-domain.txt",
"links":{
"self":"http://127.0.0.1:9001/v2/tlds/46e50ebc-1b51-41ee-bc1f-8e75a470c5be"
},
"created_at":"2014-01-23T19:59:53.985455",
"updated_at":null,
"id":"46e50ebc-1b51-41ee-bc1f-8e75a470c5be",
"name":"net"
}
],
"links":{
"self":"http://127.0.0.1:9001/v2/tlds"
}
}
:form created_at: timestamp
:form updated_at: timestamp
:form name: tld name
:form id: uuid
:form description: UTF-8 text field
:form links: links to traverse the list
:statuscode 200: OK
:statuscode 401: Access Denied
Update a Tld
---------------
.. http:patch:: /tlds/(uuid:id)
updates a tld
**Example request**:
.. sourcecode:: http
PATCH /tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"name" : "org",
"description" : "Updated the name from com to org"
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"description":"Updated the name from com to org",
"links":{
"self":"http://127.0.0.1:9001/v2/tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9"
},
"created_at":"2014-01-23T18:39:26.710827",
"updated_at":"2014-01-23T20:35:12.449599",
"id":"5abe514c-9fb5-41e8-ab73-5ed25f8a73e9",
"name":"org"
}
:form created_at: timestamp
:form updated_at: timestamp
:form name: tld name
:form id: uuid
:form description: UTF-8 text field
:form links: links to traverse the list
:statuscode 200: OK
:statuscode 401: Access Denied
:statuscode 404: Tld not found
:statuscode 409: Duplicate Tld
Delete a Tld
---------------
.. http:delete:: /tlds/(uuid:id)
delete a tld
**Example request**:
.. sourcecode:: http
DELETE /tlds/5abe514c-9fb5-41e8-ab73-5ed25f8a73e9 HTTP/1.1
Host: example.com
**Example response**:
.. sourcecode:: http
HTTP/1.1 204 No Content
Content-Type: application/json; charset=UTF-8
Content-Length: 0
:statuscode 204: No Content
:statuscode 401: Access Denied
:statuscode 404: Tld not found

265
doc/source/rest/v2/tsigkeys.rst
View File

@ -1,265 +0,0 @@
..
Copyright 2015 NEC Corporation. All rights reserved.
Author: Sonu Kumar <sonu.kumar@nectechnologies.in>
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.
=======
Tsigkey
=======
Transaction signatures (TSIG) is a mechanism used to secure DNS messages and
to provide secure server-to-server communication (usually between master and
slave server, but can be extended for dynamic updates as well).
Transaction Signatures, or TSIG for short, add cryptographic signatures as a
method of authenticating a DNS conversation. It uses a shared secret to
establish trust between the communicating parties.
Create Tsigkeys
===============
.. http:post:: /tsigkeys
Create a new Tsigkey.
**Example request**:
.. code-block:: http
POST /tsigkeys HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
{
"name": "Example key",
"algorithm": "hmac-sha256",
"secret": "SomeSecretKey",
"scope": "POOL",
"resource_id": "6ca6baef-3305-4ad0-a52b-a82df5752b62"
}
**Example response**:
.. code-block:: http
HTTP/1.1 201 Created
Location: http://127.0.0.1:9001/v2/tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2
Content-Length: 350
Content-Type: application/json; charset=UTF-8
{
"links": {
"self": "http://127.0.0.1:9001/v2/tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2"
},
"name": "test-key",
"algorithm": "hmac-sha256",
"resource_id": "6ca6baef-3305-4ad0-a52b-a82df5752b62",
"created_at": "2015-12-21T09:48:15.000000",
"updated_at": null,
"secret": "SomeSecretKey",
"scope": "POOL",
"id": "5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2"
}
:form name: TSIG Key Name.
:form algorithm: TSIG Algorithm.
:form resource_id: Pool id or Zone id
:form secret: TSIG Secret.
:form scope: TSIG Scope.
:statuscode 201: Created
:statuscode 202: Accepted
:statuscode 401: Access Denied
Get Tsigkeys
============
.. http:get:: /tsigkeys
Get the list of Tsigkeys.
**Example request**:
.. code-block:: http
GET /tsigkeys HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
**Example response**:
.. code-block:: http
HTTP/1.1 200 OK
Content-Length: 776
Content-Type: application/json; charset=UTF-8
{
"tsigkeys": [
{
"links": {
"self": "http://127.0.0.1:9001/v2/tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2"
},
"name": "test-key",
"algorithm": "hmac-sha256",
"resource_id": "6ca6baef-3305-4ad0-a52b-a82df5752b62",
"created_at": "2015-12-21T09:48:15.000000",
"updated_at": null,
"secret": "SomeSecretKey",
"scope": "POOL",
"id": "5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2"
},
{
"links": {
"self": "http://127.0.0.1:9001/v2/tsigkeys/319c58fd-a0e0-4d69-a854-98bc49594419"
},
"name": "test-key-2",
"algorithm": "hmac-sha256",
"resource_id": "6ca6baef-3305-4ad0-a52b-a82df5752b62",
"created_at": "2015-12-21T09:51:06.000000",
"updated_at": null,
"secret": "SomeSecretKey",
"scope": "POOL",
"id": "319c58fd-a0e0-4d69-a854-98bc49594419"}
],
"links": {
"self": "http://127.0.0.1:9001/v2/tsigkeys"}
}
:statuscode 200: Success
:statuscode 401: Access Denied
Get Tsigkey
===========
.. http:get:: /tsigkeys/(uuid:id)
Retrieves a tsigkey with the specified tsigkey's ID.
**Example request:**
.. sourcecode:: http
GET /v2/tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2 HTTP/1.1
Host: 127.0.0.1:9001
Content-Type: application/json
Accept: application/json
**Example response:**
.. sourcecode:: http
Content-Length: 350
Content-Type: application/json; charset=UTF-8
X-Openstack-Request-Id: req-d8cd7f24-a735-400b-9a4b-79e175efc923
Date: Mon, 21 Dec 2015 09:59:26 GMT
{
"links": {
"self": "http://127.0.0.1:9001/v2/tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2"
},
"name": "test-key",
"algorithm": "hmac-sha256",
"resource_id": "6ca6baef-3305-4ad0-a52b-a82df5752b62",
"created_at": "2015-12-21T09:48:15.000000",
"updated_at": null,
"secret": "SomeSecretKey",
"scope": "POOL",
"id": "5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2"
}
Update Tsigkey
==============
.. http:patch:: /tsigkeys/(uuid:id)
Update a Tsigkey with the specified tsigkey's id.
**Example request**:
.. code-block:: http
PATCH /tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2 HTTP/1.1
Host: 127.0.0.1:9001
Accept: application/json
Content-Type: application/json
{
"name": "example_tsigkey",
"scope": "ZONE"
}
**Example response**:
.. code-block:: http
HTTP/1.1 200 OK
Content-Length: 381
Content-Type: application/json; charset=UTF-8
{
"links": {
"self": "http://127.0.0.1:9001/v2/tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2"
},
"name": "example_tsigkey",
"algorithm": "hmac-sha256",
"resource_id": "6ca6baef-3305-4ad0-a52b-a82df5752b62",
"created_at": "2015-12-21T09:48:15.000000",
"updated_at": "2015-12-21T10:02:18.000000",
"secret": "SomeSecretKey",
"scope": "ZONE",
"id": "5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2"
}
:form name: TSIG Key Name.
:form algorithm: TSIG Algorithm.
:form resource_id: Pool id or Zone id
:form secret: TSIG Secret.
:form scope: TSIG Scope.
:statuscode 200: Success
:statuscode 202: Accepted
:statuscode 401: Access Denied
Remove Tsigkey
==============
.. http:delete:: /tsigkeys/(uuid:id)
Remove a Tsigkey with the specified tsigkey's id.
**Example request**:
.. code-block:: http
DELETE /tsigkeys/5fa28ce8-68e3-4fdf-89c1-ed9f151b83d2 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

1105
doc/source/rest/v2/zones.rst
View File

File diff suppressed because it is too large Load Diff