designate/doc/source/rest/v1/records.rst

Records

Resource record entries are used to generate records within a zone

TODO: More detail.

Note

V1 API has been deprecated since the Kilo release.

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

Create an A record for a domain

Example request:

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": "A",
  "data": "192.0.2.3"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 399
Location: http://localhost:9001/v1/domains/89acac79-38e7-497d-807c-a011e1310438/records/2e32e609-3a4f-45ba-bdef-e50eacd345ad
Date: Fri, 02 Nov 2012 19:56:26 GMT

{
  "id": "2e32e609-3a4f-45ba-bdef-e50eacd345ad",
  "name": "www.example.com.",
  "type": "A",
  "created_at": "2012-11-02T19:56:26.366792",
  "updated_at": null,
  "domain_id": "89acac79-38e7-497d-807c-a011e1310438",
  "ttl": null,
  "priority": null,
  "data": "192.0.2.3",
  "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

IPv4 address

form domain_id

domain ID

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 404

Not Found

statuscode 409

Duplicate Record

Create a AAAA record for a domain

Example request:

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:

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

Example request:

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": "MX",
  "data": "mail.example.com.",
  "priority": 10
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 420
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": "MX",
  "created_at": "2013-01-07T00:00:00.000000",
  "updated_at": null,
  "domain_id": "89acac79-38e7-497d-807c-a011e1310438",
  "priority": 10,
  "ttl": null,
  "data": "mail.example.com.",
  "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 ttl

time-to-live numeric value in seconds

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 404

Not Found

statuscode 409

Duplicate Record

Create a CNAME record for a domain

Example request:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

Get a particular record

Example request:

GET /domains/09494b72b65b42979efb187f65a0553e/records/2e32e609-3a4f-45ba-bdef-e50eacd345ad HTTP/1.1
Host: example.com
Accept: application/json

Example response:

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

{
  "id": "2e32e609-3a4f-45ba-bdef-e50eacd345ad",
  "name": "www.example.com.",
  "type": "A",
  "created_at": "2012-11-02T19:56:26.366792",
  "updated_at": "2012-11-04T13:22:36.859786",
  "priority": null,
  "ttl": 3600,
  "data": "15.185.172.153",
  "domain_id": "89acac79-38e7-497d-807c-a011e1310438",
  "description": null
}

param domain_id

Domain ID

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

Updates a record

Example request:

PUT /domains/89acac79-38e7-497d-807c-a011e1310438/records/2e32e609-3a4f-45ba-bdef-e50eacd345ad HTTP/1.1
Host: example.com
Accept: application/json
Content-Type: application/json

{
  "name": "www.example.com.",
  "type": "A",
  "data": "192.0.2.5"
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 446
Date: Sun, 04 Nov 2012 13:22:36 GMT

{
  "id": "2e32e609-3a4f-45ba-bdef-e50eacd345ad",
  "name": "www.example.com.",
  "type": "A",
  "created_at": "2012-11-02T19:56:26.366792",
  "updated_at": "2012-11-04T13:22:36.859786",
  "priority": null,
  "ttl": 3600,
  "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 name

name of record FQDN

form type

type of record

form created_at

timestamp

form updated_at

timestamp

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 Record

Delete a record

Delete a DNS resource record

Example request:

DELETE /domains/89acac79-38e7-497d-807c-a011e1310438/records/4ad19089-3e62-40f8-9482-17cc8ccb92cb HTTP/1.1

param domain_id

domain ID

param id

record ID

Example response:

Content-Type: text/html; charset=utf-8 Content-Length: 0 Date: Sun, 04 Nov 2012 14:35:57 GMT

List Records in a Domain

Lists records of a domain

Example request:

GET /domains/89acac79-38e7-497d-807c-a011e1310438/records HTTP/1.1
Host: example.com
Accept: application/json

Example response:

Content-Type: application/json
Content-Length: 1209
Date: Sun, 04 Nov 2012 13:58:21 GMT

{
  "records": [
    {
      "id": "2e32e609-3a4f-45ba-bdef-e50eacd345ad",
      "name": "www.example.com.",
      "type": "A",
      "ttl": 3600,
      "created_at": "2012-11-02T19:56:26.000000",
      "updated_at": "2012-11-04T13:22:36.000000",
      "data": "15.185.172.153",
      "domain_id": "89acac79-38e7-497d-807c-a011e1310438",
      "tenant_id": null,
      "priority": null,
      "description": null,
      "version": 1
    },
    {
      "id": "8e9ecf3e-fb92-4a3a-a8ae-7596f167bea3",
      "name": "host1.example.com.",
      "type": "A",
      "ttl": 3600,
      "created_at": "2012-11-04T13:57:50.000000",
      "updated_at": null,
      "data": "15.185.172.154",
      "domain_id": "89acac79-38e7-497d-807c-a011e1310438",
      "tenant_id": null,
      "priority": null,
      "description": null,
      "version": 1
    },
    {
      "id": "4ad19089-3e62-40f8-9482-17cc8ccb92cb",
      "name": "web.example.com.",
      "type": "CNAME",
      "ttl": 3600,
      "created_at": "2012-11-04T13:58:16.393735",
      "updated_at": null,
      "data": "www.example.com.",
      "domain_id": "89acac79-38e7-497d-807c-a011e1310438",
      "tenant_id": null,
      "priority": null,
      "description": null,
      "version": 1
    }
  ]
}

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