Jump to: navigation, search

Difference between revisions of "Designate/APIv2"

Line 375: Line 375:
 
''' Response: '''
 
''' Response: '''
  
   HTTP/1.1 201 Created
+
   HTTP/1.1 200 Ok
  
 
== RecordSet Operations ==
 
== RecordSet Operations ==
Line 644: Line 644:
 
''' Response: '''
 
''' Response: '''
  
   HTTP/1.1 201 Created
+
   HTTP/1.1 200 Ok

Revision as of 13:11, 16 July 2013

This is a EARLY DRAFT of the Designate Version 2 API.

Basic APIv2 Requirements

  1. Switch from string based rdata to dict based rdata. This allows for a sane API for the more complex record types (SRV, GEOIP, WRR etc).
    1. This complicates simple record types, but simplifies complex record types (SRV, GEeoIP, Weigthed RR, Failover etc)
  2. Introduce the concept of RecordSets. This helps our API more accurately reflect the DNS specs, and provides saner grouping of related rdatas.
  3. Document the concept of "server pools". This allows the API to remain the same if/when we introduce private DNS instances.
  4. Provided a mechanism to prevent concurrent modifications.
  5. Pagination (See "List Zones")
  6. Filtering of result sets (See "List Zones")

TODOs

  1. Try Align with the Glance V2 and Keystone V3 APIs where possible, these are the latest OpenStack APIs and should be used as a reference where possible
  2. Ideally, we can support both dict and string based rdata's ({"weight": 0, "priority": 10, "target": "xmpp1.example.org."} AND "0 10 xmpp1.example.org.")
  3. Pagination? (See "List Zones")
  4. All tenant access?
  5. Filtering/searching syntax? (See "List Zones")
  6. Probably LOTS more

Resources

Zone

Property Type Default Required Immutable Read Only
id uuid Generated
pool_id uuid Configured
name string None
email string None
ttl int 3600
serial int Generated
version int Generated
created_at timestamp Generated
updated_at timestamp Generated

Record Set

Property Type Default Required Immutable Read Only
id uuid Generated
zone_id uuid Configured
name domainname None
type string None
ttl int nil
records list<rdata> Empty List
version int Generated
created_at timestamp Generated
updated_at timestamp Generated

RData

A

Property Type Default Required Immutable Read Only
address ipv4 None

AAAA

Property Type Default Required Immutable Read Only
address ipv6 None

CNAME

Property Type Default Required Immutable Read Only
cname hostname None

MX

Property Type Default Required Immutable Read Only
preference int None
exchange hostname None

NS

Property Type Default Required Immutable Read Only
nsdname hostname None

PTR

Property Type Default Required Immutable Read Only
ptrdname hostname None

SOA

{note:title=Additional Restrictions}Only 1 SOA record may be present in a zone, and it must be at the root of the zone{note}

Property Type Default Required Immutable Read Only
mname domainname Generated
rname domainname Generated
serial int Generated
refresh int Generated
retry int Generated
expire int Generated
minimun int Generated

SPF

Property Type Default Required Immutable Read Only
text string None

SRV

Property Type Default Required Immutable Read Only
priority int None
weight int None
port int None
target hostname None

SSHFP

Property Type Default Required Immutable Read Only
algorithm int None
type int 1
fingerprint string None

TXT

Property Type Default Required Immutable Read Only
text string None

Usage

Zone Operations

Create Zone

Request:

 POST /v2/zones HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 Content-Type: application/json
 X-Auth-Token: HPAuth_*****
 {
   "zone": {
     "name": "example.org.",
     "email": "joe@example.org.",
     "ttl": 7200
   }
 }

Response:

   HTTP/1.1 201 Created
 Vary: Accept
 Content-Type: application/json
 Location: https://region-a.geo-1.dns.hpcloudsvc.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3
 {
   "zone": {
     "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
     "pool_id": "7d62d10d-3a16-4828-85dd-7b3fdc0ba989",
     "name": "example.org.",
     "email": "joe@example.org.",
     "ttl": 7200,
     "serial": 1351800588,
     "version": 1,
     "created_at": "...",
     "updated_at": null
   }
 }

Get Zone

Request:

 GET /v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 X-Auth-Token: HPAuth_*****

Response:

 HTTP/1.1 200 OK
 Vary: Accept
 Content-Type: application/json
 {
   "zone": {
     "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
     "pool_id": "7d62d10d-3a16-4828-85dd-7b3fdc0ba989",
     "name": "example.org.",
     "email": "joe@example.org.",
     "ttl": 7200,
     "serial": 1351800588,
     "version": 1,
     "created_at": "...",
     "updated_at": null
   }
 }

List Zones

Request:

 GET /v2/zones HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 X-Auth-Token: HPAuth_*****

Request (With Filters):

 GET /v2/zones?email=joe%40example.net HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 X-Auth-Token: HPAuth_*****

Request (With Paging):

 GET /v2/zones?per_page=10&page=2 HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 X-Auth-Token: HPAuth_*****

Response:

 HTTP/1.1 200 OK
 Vary: Accept
 Content-Type: application/json
 Link: https://endpoint/v2/zones?per_page=10&page=1;rel=previous
 Link: https://endpoint/v2/zones?per_page=10&page=3;rel=next
 {
   "zones": [{
     "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
     "pool_id": "7d62d10d-3a16-4828-85dd-7b3fdc0ba989",
     "name": "example.org.",
     "email": "joe@example.org.",
     "ttl": 7200,
     "serial": 1351800588,
     "version": 1,
     "created_at": "...",
     "updated_at": null
   }, {
     "id": "fdd7b0dc-52a3-491e-829f-41d18e1d3ada",
     "pool_id": "7d62d10d-3a16-4828-85dd-7b3fdc0ba989",
     "name": "example.net.",
     "email": "joe@example.net.",
     "ttl": 7200,
     "serial": 1351800588,
     "version": 1,
     "created_at": "...",
     "updated_at": null
   }]
 }

Update Zone

In both examples below, we update the TTL to 3600.

Request Option 1 - POST Request:

 POST https://region-a.geo-1.dns.hpcloudsvc.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 Content-Type: application/json
 X-Auth-Token: HPAuth_*****
 {
   "zone": {
     "ttl": 3600
   }
 }


Request Option 2 - PATCH Request:

 PATCH https://region-a.geo-1.dns.hpcloudsvc.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 Content-Type: application/json-patch+json
 X-Auth-Token: HPAuth_*****
 [
   {"op": "test", "path": "/zone/version", "value": 1},
   {"op": "replace", "path": "/zone/ttl", "value": 3600}
 ]

Response:

 HTTP/1.1 201 Created
 Vary: Accept
 Content-Type: application/json
 {
   "zone": {
     "id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
     "pool_id": "7d62d10d-3a16-4828-85dd-7b3fdc0ba989",
     "name": "example.org.",
     "email": "joe@example.org.",
     "ttl": 3600,
     "serial": 1351800588,
     "version": 2,
     "created_at": "...",
     "updated_at": "..."
   }
 }

Delete Zone

Request:

 DELETE https://region-a.geo-1.dns.hpcloudsvc.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3 HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 X-Auth-Token: HPAuth_*****

Response:

 HTTP/1.1 200 Ok

RecordSet Operations

Create RecordSet

Create RecordSet (A)

Request:

 POST https://region-a.geo-1.dns.hpcloudsvc.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 Content-Type: application/json
 X-Auth-Token: HPAuth_*****
 {
   "recordset": {
     "name": "www.example.org.",
     "type": "A",
     "ttl": 3600,
     "records": [{
       "address": "10.1.2.3"
     },{
       "address": "10.3.2.1"
     }]
   }
 }

Response:

 HTTP/1.1 201 Created
 Vary: Accept
 Content-Type: application/json
 Location: https://region-a.geo-1.dns.hpcloudsvc.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets/9e27811d-0320-4179-abb7-0e00e371e25b
 {
   "recordset": {
     "id": "9e27811d-0320-4179-abb7-0e00e371e25b",
     "zone_id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
     "name": "www.example.org.",
     "type": "A",
     "ttl": 3600,
     "records": [{
       "address": "10.1.2.3"
     },{
       "address": "10.3.2.1"
     }],
     "version": 1,
     "created_at": "...",
     "updated_at": null
   }
 }

Create RecordSet (SRV)

Request:

 POST https://region-a.geo-1.dns.hpcloudsvc.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 Content-Type: application/json
 X-Auth-Token: HPAuth_*****
 {
   "recordset": {
     "name": "_xmpp-server._tcp.example.org.",
     "type": "SRV",
     "ttl": 3600,
     "records": [{
       "weight": 0,
       "priority": 10,
       "target": "xmpp1.example.org."
     }, {
       "weight": 0,
       "priority": 20,
       "target": "xmpp2.example.org."
     }]
   }
 }

Response:

 HTTP/1.1 201 Created
 Vary: Accept
 Content-Type: application/json
 Location: https://region-a.geo-1.dns.hpcloudsvc.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets/9e27811d-0320-4179-abb7-0e00e371e25b
 {
   "recordset": {
     "id": "9e27811d-0320-4179-abb7-0e00e371e25b",
     "zone_id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
     "name": "_xmpp-server._tcp.example.org.",
     "type": "SRV",
     "ttl": 3600,
     "records": [{
       "weight": 0,
       "priority": 10,
       "target": "xmpp1.example.org."
     }, {
       "weight": 0,
       "priority": 20,
       "target": "xmpp2.example.org."
     }],
     "version": 1,
     "created_at": "...",
     "updated_at": null
   }
 }

Get RecordSet

Request:

 GET https://region-a.geo-1.dns.hpcloudsvc.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets/9e27811d-0320-4179-abb7-0e00e371e25b HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 X-Auth-Token: HPAuth_*****

Response:

 HTTP/1.1 200 OK
 Vary: Accept
 Content-Type: application/json
 {
   "recordset": {
     "id": "9e27811d-0320-4179-abb7-0e00e371e25b",
     "zone_id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
     "name": "www.example.org.",
     "type": "A",
     "ttl": 3600,
     "records": [{
       "address": "10.1.2.3"
     },{
       "address": "10.3.2.1"
     }],
     "version": 1,
     "created_at": "...",
     "updated_at": null
   }
 }

List RecordSets

Request:

 GET /v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 X-Auth-Token: HPAuth_*****

Response:

 HTTP/1.1 200 OK
 Vary: Accept
 Content-Type: application/json
 {
   "recordsets": [{
     "id": "9e27811d-0320-4179-abb7-0e00e371e25b",
     "zone_id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
     "name": "www.example.org.",
     "type": "A",
     "ttl": 3600,
     "records": [{
       "address": "10.1.2.3"
     },{
       "address": "10.3.2.1"
     }],
     "version": 1,
     "created_at": "...",
     "updated_at": null
   }, {
     "id": "9e27811d-0320-4179-abb7-0e00e371e25b",
     "zone_id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
     "name": "_xmpp-server._tcp.example.org.",
     "type": "SRV",
     "ttl": 3600,
     "records": [{
       "weight": 0,
       "priority": 10,
       "target": "xmpp1.example.org."
     }, {
       "weight": 0,
       "priority": 20,
       "target": "xmpp2.example.org."
     }],
     "version": 1,
     "created_at": "...",
     "updated_at": null
   }]
 }

Update RecordSet

In both examples below, we add "127.0.0.1" to the RRSet records list.

Request Option 1 - POST Request:

 POST https://region-a.geo-1.dns.hpcloudsvc.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets/9e27811d-0320-4179-abb7-0e00e371e25b HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 Content-Type: application/json
 X-Auth-Token: HPAuth_*****
 {
   "recordset": {
     "records": [{
       "address": "10.1.2.3"
     }, {
       "address": "10.3.2.1"
     }, {
       "address": "127.0.0.1"
     }]
   }
 }


Request Option 2 - PATCH Request:

 PATCH https://region-a.geo-1.dns.hpcloudsvc.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets/9e27811d-0320-4179-abb7-0e00e371e25b HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 Accept: application/json
 Content-Type: application/json-patch+json
 X-Auth-Token: HPAuth_*****
 [
   {"op": "test", "path": "/recordset/version", "value": 1},
   {"op": "add", "path": "/recordset/records/-", "value": {"address": "127.0.0.1"}}
 ]


Response:

 HTTP/1.1 201 Created
 Vary: Accept
 Content-Type: application/json
 {
   "recordset": {
     "id": "9e27811d-0320-4179-abb7-0e00e371e25b",
     "zone_id": "a86dba58-0043-4cc6-a1bb-69d5e86f3ca3",
     "name": "www.example.org.",
     "type": "A",
     "ttl": 3600,
     "records": [{
       "address": "10.1.2.3"
     }, {
       "address": "10.3.2.1"
     }, {
       "address": "127.0.0.1"
     }],
     "version": 2,
     "created_at": "...",
     "updated_at": "..."
   }
 }

Delete RecordSet

Request:

 DELETE https://region-a.geo-1.dns.hpcloudsvc.com/v2/zones/a86dba58-0043-4cc6-a1bb-69d5e86f3ca3/recordsets/9e27811d-0320-4179-abb7-0e00e371e25b HTTP/1.1
 Host: region-a.geo-1.dns.hpcloudsvc.com
 X-Auth-Token: HPAuth_*****

Response:

 HTTP/1.1 200 Ok