openstack/designate
Code Issues Proposed changes

Add more API documentation for record types

Browse Source 
Add examples to the REST API documentation section for each of
the record types supported. Currently, there are only examples
for types 'A' and 'MX'.

Change-Id: Iba9a8e4b88312b6266b46fb3e353076dd03cab8f
Fixes: bug #1204578
This commit is contained in:
Betsy Luzader 2013-08-09 09:58:38 -05:00
parent ad1935a9da
commit 85f674b0b8
1 changed files with 510 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

528
doc/source/rest/records.rst
View File

@ -25,7 +25,7 @@ Create Record
{
"name": "www.example.com.",
"type": "A",
"data": "15.185.172.152"
"data": "192.0.2.3"
}
@ -46,24 +46,89 @@ Create Record
"created_at": "2012-11-02T19:56:26.366792",
"updated_at": null,
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"ttl": 3600,
"data": "15.185.172.152",
"ttl": null,
"priority": null,
"data": "192.0.2.3",
"description": null
}
:param domain_id: domain ID
:form id: record id
:form id: record ID
:form name: name of record FQDN
:form type: type of record
:form created_at: timestamp
:form updated_at: timestamp
:form ttl: time-to-live numeric value in seconds
:form data: value of record
:form data: IPv4 address
:form domain_id: domain ID
:form priority: priority of MX record
:form priority: must be null for 'A' record
:form description: UTF-8 text field
:statuscode 200: Success
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 409: Duplicate Domain
:statuscode 404: Not Found
:statuscode 409: Duplicate Record
Create a AAAA record for a domain
**Example request**:
.. sourcecode:: http
POST /domains/89acac79-38e7-497d-807c-a011e1310438/records HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"name": "www.example.com.",
"type": "AAAA",
"data": "2001:db8:0:1234:0:5678:9:12"
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 303
Location: http://localhost:9001/v1/domains/89acac79-38e7-497d-807c-a011e1310438/records/11112222-3333-4444-5555-666677778888
Date: Fri, 02 Nov 2012 19:56:26 GMT
{
"id": "11112222-3333-4444-5555-666677778888",
"name": "www.example.com.",
"type": "AAAA",
"created_at": "2013-01-07T00:00:00.000000",
"updated_at": null,
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"priority": null,
"ttl": null,
"data": "2001:db8:0:1234:0:5678:9:12",
"description": null
}
:param domain_id: domain ID
:form id: record ID
:form name: name of record FQDN
:form type: type of record
:form created_at: timestamp
:form updated_at: timestamp
:form ttl: time-to-live numeric value in seconds
:form data: IPv6 address
:form domain_id: domain ID
:form priority: must be null for 'AAAA' records
:form description: UTF-8 text field
:statuscode 200: Success
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 404: Not Found
:statuscode 409: Duplicate Record
Create an MX record for a domain
@ -102,13 +167,14 @@ Create Record
"updated_at": null,
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"priority": 10,
"ttl": 3600,
"data": "mail.example.com."
"ttl": null,
"data": "mail.example.com.",
"description": null
}
:param domain_id: domain ID
:form id: record id
:form id: record ID
:form name: name of record FQDN
:form type: type of record
:form created_at: timestamp
@ -116,10 +182,427 @@ Create Record
:form data: value of record
:form domain_id: domain ID
:form priority: priority of MX record
:form description: UTF-8 text field
:statuscode 200: Success
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 409: Duplicate Domain
:statuscode 404: Not Found
:statuscode 409: Duplicate Record
Create a CNAME record for a domain
**Example request**:
.. sourcecode:: http
POST /domains/89acac79-38e7-497d-807c-a011e1310438/records HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"name": "www.example.com.",
"type": "CNAME",
"data": "example.com"
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 303
Location: http://localhost:9001/v1/domains/89acac79-38e7-497d-807c-a011e1310438/records/11112222-3333-4444-5555-666677778889
Date: Fri, 02 Nov 2012 19:56:26 GMT
{
"id": "11112222-3333-4444-5555-666677778889",
"name": "www.example.com.",
"type": "CNAME",
"created_at": "2013-01-07T00:00:00.000000",
"updated_at": null,
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"priority": null,
"ttl": null,
"data": "example.com",
"description": null
}
:param domain_id: domain ID
:form id: record ID
:form name: alias for the CNAME
:form type: type of record
:form created_at: timestamp
:form updated_at: timestamp
:form ttl: time-to-live numeric value in seconds
:form data: CNAME
:form domain_id: domain ID
:form priority: must be null for 'CNAME' records
:form description: UTF-8 text field
:statuscode 200: Success
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 404: Not Found
:statuscode 409: Duplicate Record
Create a TXT record for a domain
**Example request**:
.. sourcecode:: http
POST /domains/89acac79-38e7-497d-807c-a011e1310438/records HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"name": "www.example.com.",
"type": "TXT",
"data": "This is a TXT record"
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 303
Location: http://localhost:9001/v1/domains/89acac79-38e7-497d-807c-a011e1310438/records/11112222-3333-4444-5555-666677778899
Date: Fri, 02 Nov 2012 19:56:26 GMT
{
"id": "11112222-3333-4444-5555-666677778899",
"name": "www.example.com.",
"type": "TXT",
"created_at": "2013-01-07T00:00:00.000000",
"updated_at": null,
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"priority": null,
"ttl": null,
"data": "This is a TXT record",
"description": null
}
:param domain_id: domain ID
:form id: record ID
:form name: name of record FQDN
:form type: type of record
:form created_at: timestamp
:form updated_at: timestamp
:form ttl: time-to-live numeric value in seconds
:form data: Text associated with record.
:form domain_id: domain ID
:form priority: must be null for 'TXT' records
:form description: UTF-8 text field
:statuscode 200: Success
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 404: Not Found
:statuscode 409: Duplicate Record
Create an SRV record for a domain
**Example request**:
.. sourcecode:: http
POST /domains/89acac79-38e7-497d-807c-a011e1310438/records HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"name": "_sip._tcp.example.com.",
"type": "SRV",
"data": "0 5060 sip.example.com"
"priority": 30
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 399
Location: http://localhost:9001/v1/domains/89acac79-38e7-497d-807c-a011e1310438/records/11112222-3333-4444-5555-666677778999
Date: Fri, 02 Nov 2012 19:56:26 GMT
{
"id": "11112222-3333-4444-5555-66667777899",
"name": "_sip._tcp.example.com.",
"type": "SRV",
"created_at": "2012-11-02T19:56:26.366792",
"updated_at": null,
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"ttl": null,
"priority" : 30,
"data": "0 5060 sip.example.com",
"description": null
}
:param domain_id: domain ID
:form id: record ID
:form name: name of service
:form type: type of record
:form created_at: timestamp
:form updated_at: timestamp
:form ttl: time-to-live numeric value in seconds
:form data: weight port target
:form domain_id: domain ID
:form priority: priority of SRV record
:form description: UTF-8 text field
:statuscode 200: Success
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 404: Not Found
:statuscode 409: Duplicate Record
Create an NS record for a domain
**Example request**:
.. sourcecode:: http
POST /domains/89acac79-38e7-497d-807c-a011e1310438/records HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"name": ".example.com.",
"type": "NS",
"data": "ns1.example.com."
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 399
Location: http://localhost:9001/v1/domains/89acac79-38e7-497d-807c-a011e1310438/records/11112222-3333-4444-5555-666677789999
Date: Fri, 02 Nov 2012 19:56:26 GMT
{
"id": "11112222-3333-4444-5555-666677789999",
"name": ".example.com.",
"type": "NS",
"created_at": "2012-11-02T19:56:26.366792",
"updated_at": null,
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"ttl": null,
"priority" : null,
"data": "ns1.example.com",
"description": null
}
:param domain_id: domain ID
:form id: record ID
:form name: record name
:form type: type of record
:form created_at: timestamp
:form updated_at: timestamps
:form ttl: time-to-live numeric value in seconds
:form data: record value
:form domain_id: domain ID
:form priority: must be null for 'NS' record
:form description: UTF-8 text field
:statuscode 200: Success
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 404: Not Found
:statuscode 409: Duplicate Record
Create a PTR record for a domain
**Example request**:
.. sourcecode:: http
POST /domains/89acac79-38e7-497d-807c-a011e1310438/records HTTP/1.1
Host: 2.3.192.in-addr.arpa.
Accept: application/json
Content-Type: application/json
{
"name": "1.2.3.192.in-addr.arpa.",
"type": "PTR",
"data": "www.example.com."
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 399
Location: http://localhost:9001/v1/domains/89acac79-38e7-497d-807c-a011e1310438/records/11112222-3333-4444-5555-666677889999
Date: Fri, 02 Nov 2012 19:56:26 GMT
{
"id": "11112222-3333-4444-5555-666677889999",
"name": "1.2.3.192.in-addr.arpa.",
"type": "PTR",
"created_at": "2012-11-02T19:56:26.366792",
"updated_at": null,
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"ttl": null,
"priority" : null,
"data": "www.example.com",
"description": null
}
:param domain_id: domain ID
:form id: record ID
:form name: PTR record name
:form type: type of record
:form created_at: timestamp
:form updated_at: timestamp
:form ttl: time-to-live numeric value in seconds
:form data: DNS record value
:form domain_id: domain ID
:form priority: must be null for 'PTR' record
:form description: UTF-8 text field
:statuscode 200: Success
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 404: Not Found
:statuscode 409: Duplicate Record
Create an SPF record for a domain
**Example request**:
.. sourcecode:: http
POST /domains/89acac79-38e7-497d-807c-a011e1310438/records HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"name": ".example.com.",
"type": "SPF",
"data": "v=spf1 +mx a:colo.example.com/28 -all"
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 399
Location: http://localhost:9001/v1/domains/89acac79-38e7-497d-807c-a011e1310438/records/11112222-3333-4444-5555-666678889999
Date: Fri, 02 Nov 2012 19:56:26 GMT
{
"id": "11112222-3333-4444-5555-666678889999",
"name": ".example.com.",
"type": "SPF",
"created_at": "2012-11-02T19:56:26.366792",
"updated_at": null,
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"ttl": null,
"priority" : null,
"data": "v=spf1 +mx a:colo.example.com/28 -all",
"description": null
}
:param domain_id: domain ID
:form id: record ID
:form name: name of record
:form type: type of record
:form created_at: timestamp
:form updated_at: timestamp
:form ttl: time-to-live numeric value in seconds
:form data: record value
:form domain_id: domain ID
:form priority: must be null for 'SPF' record
:form description: UTF-8 text field
:statuscode 200: Success
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 404: Not Found
:statuscode 409: Duplicate Record
Create an SSHFP record for a domain
**Example request**:
.. sourcecode:: http
POST /domains/89acac79-38e7-497d-807c-a011e1310438/records HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json
{
"name": "www.example.com.",
"type": "SSHFP",
"data": "2 1 6c3c958af43d953f91f40e0d84157f4fe7b4a898"
}
**Example response**:
.. sourcecode:: http
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 399
Location: http://localhost:9001/v1/domains/89acac79-38e7-497d-807c-a011e1310438/records/11112222-3333-4444-5555-666778889999
Date: Fri, 02 Nov 2012 19:56:26 GMT
{
"id": "11112222-3333-4444-5555-666778889999",
"name": "www.example.com.",
"type": "SSHFP",
"created_at": "2012-11-02T19:56:26.366792",
"updated_at": null,
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"ttl": null,
"priority" : null,
"data": "2 1 6c3c958af43d953f91f40e0d84157f4fe7b4a898"
"description": null
}
:param domain_id: domain ID
:form id: record ID
:form name: name of record
:form type: type of record
:form created_at: timestamp
:form updated_at: timestamp
:form ttl: time-to-live numeric value in seconds
:form data: algorithm number, fingerprint type, fingerprint
:form domain_id: domain ID
:form priority: must be null for 'SSHFP' record
:form description: UTF-8 text field
:statuscode 200: Success
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 404: Not Found
:statuscode 409: Duplicate Record
Get a Record
-------------
@ -153,12 +636,13 @@ Get a Record
"priority": null,
"ttl": 3600,
"data": "15.185.172.153",
"domain_id": "89acac79-38e7-497d-807c-a011e1310438"
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"description": null
}
:param domain_id: Domain ID
:param id: Record ID
:form id: record id
:form id: record ID
:form name: name of record FQDN
:form type: type of record
:form created_at: timestamp
@ -166,9 +650,11 @@ Get a Record
:form priority: priority of record
:form ttl: time-to-live numeric value in seconds
:form data: value of record
:form description: UTF-8 text field
:form domain_id: domain ID
:statuscode 200: Success
:statuscode 401: Access Denied
:statuscode 404: Record Not Found
Update a record
---------------
@ -188,7 +674,7 @@ Update a record
{
"name": "www.example.com.",
"type": "A",
"data": "15.185.172.153"
"data": "192.0.2.5"
}
**Example response**:
@ -208,13 +694,14 @@ Update a record
"updated_at": "2012-11-04T13:22:36.859786",
"priority": null,
"ttl": 3600,
"data": "15.185.172.153",
"domain_id": "89acac79-38e7-497d-807c-a011e1310438"
"data": "192.0.2.5",
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"description": null
}
:param domain_id: domain ID
:param id: record ID
:form id: record id
:form id: record ID
:form name: name of record FQDN
:form type: type of record
:form created_at: timestamp
@ -222,11 +709,12 @@ Update a record
:form priority: priority of record
:form ttl: time-to-live numeric value in seconds
:form data: value of record
:form description: UTF-8 text field
:form domain_id: domain ID
:statuscode 200: Success
:statuscode 401: Access Denied
:statuscode 400: Invalid Object
:statuscode 409: Duplicate Domain
:statuscode 409: Duplicate Record
Delete a record
---------------
@ -287,6 +775,7 @@ List Records in a Domain
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"tenant_id": null,
"priority": null,
"description": null,
"version": 1,
},
{
@ -300,6 +789,7 @@ List Records in a Domain
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"tenant_id": null,
"priority": null,
"description": null,
"version": 1,
},
{
@ -313,6 +803,7 @@ List Records in a Domain
"domain_id": "89acac79-38e7-497d-807c-a011e1310438",
"tenant_id": null,
"priority": null,
"description": null,
"version": 1,
}
]
@ -327,6 +818,7 @@ List Records in a Domain
:form priority: priority of record
:form ttl: time-to-live numeric value in seconds
:form data: value of record
:form description: UTF-8 text field
:form domain_id: domain ID
:statuscode 200: Success
:statuscode 401: Access Denied