Domains operations#

Use the Domains operations to view and manage domains and subdomains for a Rackspace Cloud account.

List domains#

GET /v1.0/{account}/domains

Lists all domains manageable by the account specified. Displays IDs and names only.

These calls provide a list of all DNS domains manageable by a given account. The resulting list is flat, and does not break the domains down hierarchically by subdomain. All representative domains are included in the list, even if a domain is conceptually a subdomain of another domain in the list.

Note

These calls return by default a maximum of 100 items at a time if no limit is specified. To navigate the collection returned, the parameters limit and offset can be set in the URI (for example: limit=10 & offset=0 ), as described in Paginated collections.

In the examples that follow, the request is made for a limit of 10 records, starting at offset 20 (record 21).

Note

Because the current set of 10 records in the previous response examples begins at offset=20, note that the previous link points to a group of 10 records starting at offset=10, while the next link points to a group of 10 records starting at offset=30.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String

Arbitrary character string generated by the authentication service in response to valid credentials.

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

This operation does not accept a request body.

Example List domains: XML request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains?limit=10&offset=20
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example List domains: JSON request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains?limit=10&offset=20
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Response#

Example List domains: XML response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 2000

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domains totalEntries="114" xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <domain id="2725233" accountId="1234" name="example.com" emailAddress="sample@rackspace.com" updated="2011-06-24T01:23:15Z" created="2011-06-24T01:12:51Z" comment="Optional domain comment..."/>
    <domain id="2725257" accountId="1234" name="sub1.example.com" emailAddress="sample@rackspace.com" updated="2011-06-23T03:09:34Z" created="2011-06-23T03:09:33Z" comment="1st sample subdomain"/>
    <domain id="2725258" accountId="1234" name="sub2.example.com" emailAddress="sample@rackspace.com" updated="2011-06-23T03:52:55Z" created="2011-06-23T03:52:55Z" comment="1st sample subdomain"/>
    <domain id="2725260" accountId="1234" name="north.example.com" emailAddress="sample@rackspace.com" updated="2011-06-23T03:53:10Z" created="2011-06-23T03:53:09Z"/>
    <domain id="2725261" accountId="1234" name="south.example.com" emailAddress="sample@rackspace.com" updated="2011-06-23T03:53:14Z" created="2011-06-23T03:53:14Z" comment="Final sample subdomain"/>
    <domain id="2725352" accountId="1234" name="region2.example.net" updated="2011-06-23T20:21:06Z" created="2011-06-23T19:24:27Z"/>
    <domain id="2718984" accountId="1234" name="example.org" updated="2011-05-03T14:47:32Z" created="2011-05-03T14:47:30Z"/>
    <domain id="2722346" accountId="1234" name="rackspace.example" updated="2011-06-21T15:54:31Z" created="2011-06-15T19:02:07Z"/>
    <domain id="2722347" accountId="1234" name="dnsaas.example" updated="2011-06-21T15:54:31Z" created="2011-06-15T19:02:07Z" comment="Sample comment"/>
    <ns2:link href="https://dns.api.rackspacecloud.com/v1.0/1234/domains?limit=10&amp;offset=10" rel="previous"></ns2:link>
    <ns2:link href="https://dns.api.rackspacecloud.com/v1.0/1234/domains?limit=10&amp;offset=30" rel="next"></ns2:link>
</domains>

Example List domains: JSON response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 2364

{
  "domains" : [ {
    "name" : "example.com",
    "id" : 2725233,
    "comment" : "Optional domain comment...",
    "updated" : "2011-06-24T01:23:15.000+0000",
    "accountId" : 1234,
    "emailAddress" : "sample@rackspace.com",
    "created" : "2011-06-24T01:12:51.000+0000"
  }, {
    "name" : "sub1.example.com",
    "id" : 2725257,
    "comment" : "1st sample subdomain",
    "updated" : "2011-06-23T03:09:34.000+0000",
    "accountId" : 1234,
    "emailAddress" : "sample@rackspace.com",
    "created" : "2011-06-23T03:09:33.000+0000"
  }, {
    "name" : "sub2.example.com",
    "id" : 2725258,
    "comment" : "1st sample subdomain",
    "updated" : "2011-06-23T03:52:55.000+0000",
    "accountId" : 1234,
    "emailAddress" : "sample@rackspace.com",
    "created" : "2011-06-23T03:52:55.000+0000"
  }, {
    "name" : "north.example.com",
    "id" : 2725260,
    "updated" : "2011-06-23T03:53:10.000+0000",
    "accountId" : 1234,
    "emailAddress" : "sample@rackspace.com",
    "created" : "2011-06-23T03:53:09.000+0000"
  }, {
    "name" : "south.example.com",
    "id" : 2725261,
    "comment" : "Final sample subdomain",
    "updated" : "2011-06-23T03:53:14.000+0000",
    "accountId" : 1234,
    "emailAddress" : "sample@rackspace.com",
    "created" : "2011-06-23T03:53:14.000+0000"
  }, {
    "name" : "region2.example.net",
    "id" : 2725352,
    "updated" : "2011-06-23T20:21:06.000+0000",
    "accountId" : 1234,
    "created" : "2011-06-23T19:24:27.000+0000"
  }, {
    "name" : "example.org",
    "id" : 2718984,
    "updated" : "2011-05-03T14:47:32.000+0000",
    "accountId" : 1234,
    "created" : "2011-05-03T14:47:30.000+0000"
  }, {
    "name" : "rackspace.example",
    "id" : 2722346,
    "updated" : "2011-06-21T15:54:31.000+0000",
    "accountId" : 1234,
    "created" : "2011-06-15T19:02:07.000+0000"
  }, {
    "name" : "dnsaas.example",
    "id" : 2722347,
    "comment" : "Sample comment",
    "updated" : "2011-06-21T15:54:31.000+0000",
    "accountId" : 1234,
    "created" : "2011-06-15T19:02:07.000+0000"
  } ],
  "links" : [ {
    "content" : "",
    "href" : "https://dns.api.rackspacecloud.com/v1.0/1234/domains?limit=10&offset=10",
    "rel" : "previous"
  }, {
    "content" : "",
    "href" : "https://dns.api.rackspacecloud.com/v1.0/1234/domains?limit=10&offset=30",
    "rel" : "next"
  } ],
  "totalEntries" : 114
}

List domains by name#

GET /v1.0/{account}/domains

Filters domains by domain name: list all domains manageable by the account specified that exactly match the value of the name parameter.

Note that you can use the query parameter name to filter domains by domain name: list all domains manageable by the account specified that exactly match the fully qualified value of the name parameter. Note that if there is no exact match, no results are returned.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

This table shows the query parameters for the request:

Name

Type

Description

name

String

Name of the domain to find.

This operation does not accept a request body.

Example Filter by Fully Qualified domain Name: XML request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains?name=region2.example.net
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example Filter by Fully Qualified domain Name: JSON request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains?name=region2.example.net
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Example Filter by Fully Qualified Subdomain Name: XML request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains?name=sub1.example.com
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example Filter by Fully Qualified Subdomain Name: JSON request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains?name=sub1.example.com
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Response#

Example Filter by Fully Qualified domain Name: XML response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 371

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domains totalEntries="114" xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <domain id="2725352" name="region2.example.net" updated="2011-06-23T20:21:06Z" created="2011-06-23T19:24:27Z"/>
</domains>

Example Filter by Fully Qualified domain Name: JSON response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 202

{
  "domains" : [ {
    "name" : "region2.example.net",
    "id" : 2725352,
    "updated" : "2011-06-23T20:21:06.000+0000",
    "created" : "2011-06-23T19:24:27.000+0000"
  } ],
  "totalEntries" : 114
}

Example Filter by Fully Qualified Subdomain Name: XML response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 435

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domains totalEntries="114" xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <domain id="2725257" name="sub1.example.com" emailAddress="sample@rackspace.com" updated="2011-06-23T03:09:34Z" created="2011-06-23T03:09:33Z" comment="1st sample subdomain"/>
</domains>

Example Filter by Fully Qualified Subdomain Name: JSON response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 284

{
  "domains" : [ {
    "name" : "sub1.example.com",
    "id" : 2725257,
    "comment" : "1st sample subdomain",
    "updated" : "2011-06-23T03:09:34.000+0000",
    "emailAddress" : "sample@rackspace.com",
    "created" : "2011-06-23T03:09:33.000+0000"
  } ],
  "totalEntries" : 114
}

Create domain#

POST /v1.0/{account}/domains

Creates a domain with the configuration defined by the request.

Note

This call returns an asynchronous response, See Synchronous and asynchronous responses for more details and examples of the way that asynchronous responses work.

Note

Subdomains are also created the same way as domains.

This call provisions one or more new DNS domains under the account specified, based on the configuration defined in the request object. If the corresponding request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response will be returned with information regarding the nature of the failure in the body of the response. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST the request again.

Note

  • Refer to DNS propagation for information about DNS propagation.

  • If you attempt to create a domain that already exists, the API will return an exception saying that the domain already exists.

  • This process allows multiple records to be created along with the domain. This is an atomic operation: if there is a failure in creation of even a single record, the entire process will fail.

  • When a domain is created, and no Time To Live (TTL) is specified, the SOA minTTL (3600 seconds) is used as the default. When a record is added without a specified TTL, it will receive the domain TTL by default. When the domain or record TTL is supplied by the user, either via a create or update call, the TTL values must be 300 seconds or more.

  • Subdomains are managed in separate zone files in the DNS system and will add some overhead to domain management.

The following examples show the Create domains requests:

Note

The following examples show the initial 202 Accepted response for the asynchronous call and indicate that the task has been accepted for processing. See Synchronous and asynchronous responses for a description of how the asynchronous call works. See also Creating a domain.

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Accepted

Request is accepted.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

409

Already Exists

The item already exists.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String

Arbitrary character string generated by the authentication service in response to valid credentials.

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

This table shows the body parameters for the request:

Name

Type

Description

domains[*].name

String

The name for the domain or subdomain. Must be a valid domain name.

domains[*].emailAddress

String

Email address to use for contacting the domain administrator.

domains[*].ttl

Integer (Optional)

If specified, must be greater than or equal to 300. The default value, if not specified, is 3600.

domains[*].comment

String (Optional)

If included, its length must be less than or equal to 160 characters.

Example Create domains: XML request

POST https://dns.api.rackspacecloud.com/v1.0/1234/domains
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 1460

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domains xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <domain name="example.com" ttl="3600" emailAddress="sample@rackspace.com" comment="Optional domain comment...">
        <recordsList>
            <record type="A" name="ftp.example.com" data="192.0.2.8" ttl="5771"/>
            <record type="A" name="example.com" data="192.0.2.17" ttl="86400"/>
            <record type="NS" name="example.com" data="ns.rackspace.com" ttl="3600"/>
            <record type="NS" name="example.com" data="ns2.rackspace.com" ttl="3600"/>
            <record type="MX" name="example.com" data="mail.example.com" ttl="3600" priority="5"/>
            <record type="CNAME" name="www.example.com" data="example.com" ttl="5400" comment="This is a comment on the CNAME record"/>
        </recordsList>
        <subdomains>
            <domain name="sub1.example.com" emailAddress="sample@rackspace.com" comment="1st sample subdomain"/>
            <domain name="sub2.example.com" emailAddress="sample@rackspace.com" comment="1st sample subdomain"/>
            <domain name="north.example.com" emailAddress="sample@rackspace.com"/>
            <domain name="south.example.com" emailAddress="sample@rackspace.com" comment="Final sample subdomain"/>
        </subdomains>
    </domain>
</domains>

Example Create domains: JSON request

POST https://dns.api.rackspacecloud.com/v1.0/1234/domains
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 1615

{
  "domains" : [ {
    "name" : "example.com",
    "comment" : "Optional domain comment...",
    "recordsList" : {
      "records" : [ {
        "name" : "ftp.example.com",
        "type" : "A",
        "data" : "192.0.2.8",
        "ttl" : 5771
      }, {
        "name" : "example.com",
        "type" : "A",
        "data" : "192.0.2.17",
        "ttl" : 86400
      }, {
        "name" : "example.com",
        "type" : "NS",
        "data" : "ns.rackspace.com",
        "ttl" : 3600
      }, {
        "name" : "example.com",
        "type" : "NS",
        "data" : "ns2.rackspace.com",
        "ttl" : 3600
      }, {
        "name" : "example.com",
        "priority" : 5,
        "type" : "MX",
        "data" : "mail.example.com",
        "ttl" : 3600
      }, {
        "name" : "www.example.com",
        "type" : "CNAME",
        "comment" : "This is a comment on the CNAME record",
        "data" : "example.com",
        "ttl" : 5400
      } ]
    },
    "subdomains" : {
      "domains" : [ {
        "name" : "sub1.example.com",
        "comment" : "1st sample subdomain",
        "emailAddress" : "sample@rackspace.com"
      }, {
        "name" : "sub2.example.com",
        "comment" : "1st sample subdomain",
        "emailAddress" : "sample@rackspace.com"
      }, {
        "name" : "north.example.com",
        "emailAddress" : "sample@rackspace.com"
      }, {
        "name" : "south.example.com",
        "comment" : "Final sample subdomain",
        "emailAddress" : "sample@rackspace.com"
      } ]
    },
    "ttl" : 3600,
    "emailAddress" : "sample@rackspace.com"
  } ]
}

Response#

Example Create domains: XML response

Status: 202 Accepted
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 1636

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domains totalEntries="114" xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <domain name="example.com" ttl="3600" emailAddress="sample@rackspace.com" comment="Optional domain comment...">
        <nameservers>
            <nameserver name="ns.rackspace.com"/>
            <nameserver name="ns2.rackspace.com"/>
        </nameservers>
        <recordsList>
            <record type="A" name="ftp.example.com" data="192.0.2.8" ttl="5771"/>
            <record type="A" name="example.com" data="192.0.2.17" ttl="86400"/>
            <record type="NS" name="example.com" data="ns.rackspace.com" ttl="3600"/>
            <record type="NS" name="example.com" data="ns2.rackspace.com" ttl="3600"/>
            <record type="MX" name="example.com" data="mail.example.com" ttl="3600" priority="5"/>
            <record type="CNAME" name="www.example.com" data="example.com" ttl="5400" comment="This is a comment on the CNAME record"/>
        </recordsList>
        <subdomains>
            <domain name="sub1.example.com" emailAddress="sample@rackspace.com" comment="1st sample subdomain"/>
            <domain name="sub2.example.com" emailAddress="sample@rackspace.com" comment="1st sample subdomain"/>
            <domain name="north.example.com" emailAddress="sample@rackspace.com"/>
            <domain name="south.example.com" emailAddress="sample@rackspace.com" comment="Final sample subdomain"/>
        </subdomains>
    </domain>
</domains>

Example Create domains: JSON response

Status: 202 Accepted
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 1761

{
  "domains" : [ {
    "name" : "example.com",
    "comment" : "Optional domain comment...",
    "nameservers" : [ {
      "name" : "ns.rackspace.com"
    }, {
      "name" : "ns2.rackspace.com"
    } ],
    "recordsList" : {
      "records" : [ {
        "name" : "ftp.example.com",
        "type" : "A",
        "data" : "192.0.2.8",
        "ttl" : 5771
      }, {
        "name" : "example.com",
        "type" : "A",
        "data" : "192.0.2.17",
        "ttl" : 86400
      }, {
        "name" : "example.com",
        "type" : "NS",
        "data" : "ns.rackspace.com",
        "ttl" : 3600
      }, {
        "name" : "example.com",
        "type" : "NS",
        "data" : "ns2.rackspace.com",
        "ttl" : 3600
      }, {
        "name" : "example.com",
        "priority" : 5,
        "type" : "MX",
        "data" : "mail.example.com",
        "ttl" : 3600
      }, {
        "name" : "www.example.com",
        "type" : "CNAME",
        "comment" : "This is a comment on the CNAME record",
        "data" : "example.com",
        "ttl" : 5400
      } ]
    },
    "subdomains" : {
      "domains" : [ {
        "name" : "sub1.example.com",
        "comment" : "1st sample subdomain",
        "emailAddress" : "sample@rackspace.com"
      }, {
        "name" : "sub2.example.com",
        "comment" : "1st sample subdomain",
        "emailAddress" : "sample@rackspace.com"
      }, {
        "name" : "north.example.com",
        "emailAddress" : "sample@rackspace.com"
      }, {
        "name" : "south.example.com",
        "comment" : "Final sample subdomain",
        "emailAddress" : "sample@rackspace.com"
      } ]
    },
    "ttl" : 3600,
    "emailAddress" : "sample@rackspace.com"
  } ],
  "totalEntries" : 114
}

Update domains#

PUT /v1.0/{account}/domains

Updates the configurations of multiple domains.

Note

This call returns an asynchronous response, as described in Synchronous and asynchronous responses.

This call modifies DNS domain(s) attributes only. Records cannot be added, modified, or deleted. Only the TTL, email address and comment attributes of a domain can be modified.

If a request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response will be returned with information regarding the nature of the failure in the body of the response. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST the request again.

Note

  • Refer to DNS propagation for information about DNS propagation.

  • A domain’s id is immutable.

  • When the domain or record TTL is supplied by the user, either via a create or update call, the TTL values must be 300 seconds or more.

Note

name cannot be specified, because the domain name cannot be modified.

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Accepted

Request is accepted.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

409

Already Exists

The item already exists.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String

Arbitrary character string generated by the authentication service in response to valid credentials.

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

This operation does not accept a request body.

Example Update domains: XML request

PUT https://dns.api.rackspacecloud.com/v1.0/1234/domains/
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 441

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domains xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <domain id="2725233" ttl="3600" emailAddress="sample@rackspace.com" comment="Optional domain comment..."/>
    <domain id="2725257" emailAddress="sample@rackspace.com" comment="1st sample subdomain"/>
</domains>

Example Update domains: JSON request

PUT https://dns.api.rackspacecloud.com/v1.0/1234/domains/
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 266

{
  "domains" : [ {
    "id" : 2725233,
    "comment" : "Optional domain comment...",
    "ttl" : 3600,
    "emailAddress" : "sample@rackspace.com"
  }, {
    "id" : 2725257,
    "comment" : "1st sample subdomain",
    "emailAddress" : "sample@rackspace.com"
  } ]
}

Response#

This operation does not return a response body.

Delete domains#

DELETE /v1.0/{account}/domains

Deletes multiple domains from an account.

Note

This call returns an asynchronous response, as described in Synchronous and asynchronous responses.

This call deletes one or more specified domains from the account; when a domain is deleted, its immediate resource records are also deleted from the account. By default, if a deleted domain had subdomains, each subdomain becomes a root domain and is not deleted; this can be overridden by the optional deleteSubdomains parameter. Utilizing the optional deleteSubdomains parameter on domains without subdomains does not result in a failure. When a domain is deleted, any and all domain data is immediately purged and is not recoverable via the API. So on a successful delete, subsequent requests for the deleted object should return itemNotFound ( 404 ).

Transactionally, delete calls behave differently than other calls in that deletes are never rolled back on exceptions, and multiple deletes in the same request do not fail as a group. Instead, each delete is attempted even if one or more fail. The response for a delete request in which one or more items fail contains information regarding which items failed as well as information regarding specific issues that caused the failure(s). See the examples that follow.

In the previous two response examples, the requested domain objects could not be deleted, because they were not found.

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Accepted

Request is accepted.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

This table shows the query parameters for the request:

Name

Type

Description

id1

String

The id for the first domain.

id2

String

The id for the next domain.

This operation does not accept a request body.

Example Delete domains: XML request

DELETE https://dns.api.rackspacecloud.com/v1.0/1234/domains?id=2725233&id=2725257
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example Delete domains: JSON request

DELETE https://dns.api.rackspacecloud.com/v1.0/1234/domains?id=2725233&id=2725257
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Response#

This operation does not return a response body.

Delete domains and subdomains#

DELETE /v1.0/{account}/domains

Deletes multiple domains and their subdomains from an account.

Note

This call returns an asynchronous response, as described in Synchronous and asynchronous responses.

This call deletes one or more specified domains from the account; when a domain is deleted, its immediate resource records are also deleted from the account. By default, if a deleted domain had subdomains, each subdomain becomes a root domain and is not deleted; this can be overridden by the optional deleteSubdomains parameter. Utilizing the optional deleteSubdomains parameter on domains without subdomains does not result in a failure. When a domain is deleted, any and all domain data is immediately purged and is not recoverable via the API. So on a successful delete, subsequent requests for the deleted object should return itemNotFound ( 404 ).

Transactionally, delete calls behave differently than other calls in that deletes are never rolled back on exceptions, and multiple deletes in the same request do not fail as a group. Instead, each delete is attempted even if one or more fail. The response for a delete request in which one or more items fail contains information regarding which items failed as well as information regarding specific issues that caused the failure(s). See the examples that follow.

In the previous two response examples, the requested domain objects could not be deleted, because they were not found.

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Accepted

Request is accepted.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

This table shows the query parameters for the request:

Name

Type

Description

id1

String

id for the first domain.

id2

String

id for the next domain.

deleteSubdomains

String

If deleteSubdomains is true, also deletes subdomains. If false, subdomains are not deleted.

This operation does not accept a request body.

Example Delete domains and subdomains: XML request

DELETE https://dns.api.rackspacecloud.com/v1.0/1234/domains?id=2725233&id=2725257&deleteSubdomains=true
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example Delete domains and subdomains: JSON request

DELETE https://dns.api.rackspacecloud.com/v1.0/1234/domains?id=2725233&id=2725257&deleteSubdomains=true
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Response#

This operation does not return a response body.

Search domains#

GET /v1.0/{account}/domains/search

Searches domains by domain name: lists all names manageable by the specified account that have the value of the name parameter as part of their name.

Note

  • Use the query parameter name to search domains by domain name. This lists all names manageable by the specified account that have the value of the name parameter as part of their name.

  • The value specified for the name parameter must contain at least 3 characters or nothing will be returned by the search.

Filter criteria may consist of:

  • Any letter (A-Za-z)

  • Numbers (0-9)

  • Hyphen (“-“)

  • 3 to 63 characters

Filter criteria should not include any of the following characters: ‘ +, | ! ” £ $ % & / ( ) = ? ^ * ç ° § ; : _ > ] [ @ à, é, ò

Note

This call returns by default a maximum of 100 items at a time if no limit is specified. To navigate the collection returned, the parameters limit and offset can be set in the URI (for example: limit=10 & offset=0 ), as described at Paginated collections.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

This table shows the query parameters for the request:

Name

Type

Description

name

String

Name of the domain to find.

This operation does not accept a request body.

Example Filter by Partial Name: XML request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/search?name=sub1.exam
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example Filter by Partial Name: JSON request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/search?name=sub1.exam
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Response#

Example Filter by Partial Name: XML response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 435

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domains totalEntries="114" xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <domain id="2725257" name="sub1.example.com" emailAddress="sample@rackspace.com" updated="2011-06-23T03:09:34Z" created="2011-06-23T03:09:33Z" comment="1st sample subdomain"/>
</domains>

Example Filter by Partial Name: JSON response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 284

{
  "domains" : [ {
    "name" : "sub1.example.com",
    "id" : 2725257,
    "comment" : "1st sample subdomain",
    "updated" : "2011-06-23T03:09:34.000+0000",
    "emailAddress" : "sample@rackspace.com",
    "created" : "2011-06-23T03:09:33.000+0000"
  } ],
  "totalEntries" : 114
}

List domain details without subdomains#

GET /v1.0/{account}/domains/{domainId}

Lists details for a specified domain, with record information but without subdomains.

This call provides the detailed output for a specified domain configured and associated with an account. This call is not capable of returning details for a domain that has been deleted.

This call does not require a request body.

Note

By default, returns a maximum of 100 items at a time if no limit is specified. To navigate the collection returned, the parameters limit and offset can be set in the URI (for example: limit=10 & offset=0 ), as described in Paginated collections.

The following examples show the default parameter settings ( showRecords = true & showSubdomains = false ) for the List domain details call. This call returns information with records but no information about subdomains. Because these parameter values are the defaults, this call works the same way if both of the parameters are omitted.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String

Arbitrary character string generated by the authentication service in response to valid credentials.

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

{domainId}

String

ID for the domain.

This operation does not accept a request body.

Example List domain details with records, no subdomains: XML request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725233?showRecords=true&showSubdomains=false
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example List domain details with records, no subdomains: JSON request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725233?showRecords=true&showSubdomains=false
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Response#

Example List domain details with records, no subdomains: XML response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 1660

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain id="2725233" accountId="1234" name="example.com" ttl="3600" emailAddress="sample@rackspace.com" updated="2011-06-24T01:23:15Z" created="2011-06-24T01:12:51Z" comment="Optional domain comment..." xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <nameservers>
        <nameserver name="ns.rackspace.com"/>
        <nameserver name="ns2.rackspace.com"/>
    </nameservers>
    <recordsList totalEntries="6">
        <record id="A-6817754" type="A" name="ftp.example.com" data="192.0.2.8" ttl="5771" updated="2011-05-19T08:07:08-05:00" created="2011-05-18T14:53:09-05:00"/>
        <record id="A-6822994" type="A" name="example.com" data="192.0.2.17" ttl="86400" updated="2011-06-24T01:12:52Z" created="2011-06-24T01:12:52Z"/>
        <record id="NS-6251982" type="NS" name="example.com" data="ns.rackspace.com" ttl="3600" updated="2011-06-24T01:12:51Z" created="2011-06-24T01:12:51Z"/>
        <record id="NS-6251983" type="NS" name="example.com" data="ns2.rackspace.com" ttl="3600" updated="2011-06-24T01:12:51Z" created="2011-06-24T01:12:51Z"/>
        <record id="MX-3151218" type="MX" name="example.com" data="mail.example.com" ttl="3600" priority="5" updated="2011-06-24T01:12:53Z" created="2011-06-24T01:12:53Z"/>
        <record id="CNAME-9778009" type="CNAME" name="www.example.com" data="example.com" ttl="5400" updated="2011-06-24T01:12:54Z" created="2011-06-24T01:12:54Z" comment="This is a comment on the CNAME record"/>
    </recordsList>
</domain>

Example List domain details with records, no subdomains: JSON response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 1975

{
  "name" : "example.com",
  "id" : 2725233,
  "comment" : "Optional domain comment...",
  "updated" : "2011-06-24T01:23:15.000+0000",
  "nameservers" : [ {
    "name" : "ns.rackspace.com"
  }, {
    "name" : "ns2.rackspace.com"
  } ],
  "accountId" : 1234,
  "recordsList" : {
    "totalEntries" : 6,
    "records" : [ {
      "name" : "ftp.example.com",
      "id" : "A-6817754",
      "type" : "A",
      "data" : "192.0.2.8",
      "updated" : "2011-05-19T13:07:08.000+0000",
      "ttl" : 5771,
      "created" : "2011-05-18T19:53:09.000+0000"
    }, {
      "name" : "example.com",
      "id" : "A-6822994",
      "type" : "A",
      "data" : "192.0.2.17",
      "updated" : "2011-06-24T01:12:52.000+0000",
      "ttl" : 86400,
      "created" : "2011-06-24T01:12:52.000+0000"
    }, {
      "name" : "example.com",
      "id" : "NS-6251982",
      "type" : "NS",
      "data" : "ns.rackspace.com",
      "updated" : "2011-06-24T01:12:51.000+0000",
      "ttl" : 3600,
      "created" : "2011-06-24T01:12:51.000+0000"
    }, {
      "name" : "example.com",
      "id" : "NS-6251983",
      "type" : "NS",
      "data" : "ns2.rackspace.com",
      "updated" : "2011-06-24T01:12:51.000+0000",
      "ttl" : 3600,
      "created" : "2011-06-24T01:12:51.000+0000"
    }, {
      "name" : "example.com",
      "priority" : 5,
      "id" : "MX-3151218",
      "type" : "MX",
      "data" : "mail.example.com",
      "updated" : "2011-06-24T01:12:53.000+0000",
      "ttl" : 3600,
      "created" : "2011-06-24T01:12:53.000+0000"
    }, {
      "name" : "www.example.com",
      "id" : "CNAME-9778009",
      "type" : "CNAME",
      "comment" : "This is a comment on the CNAME record",
      "data" : "example.com",
      "updated" : "2011-06-24T01:12:54.000+0000",
      "ttl" : 5400,
      "created" : "2011-06-24T01:12:54.000+0000"
    } ]
  },
  "ttl" : 3600,
  "emailAddress" : "sample@rackspace.com",
  "created" : "2011-06-24T01:12:51.000+0000"
}

Show domain#

GET /v1.0/{account}/domains/{domainId}

Shows details for a specified domain. Displays details, as specified by the showRecords and showSubdomains parameters.

This call provides the detailed output for a specified domain configured and associated with an account. This call is not capable of returning details for a domain that has been deleted.

This call does not require a request body.

Note

By default, returns a maximum of 100 items at a time if no limit is specified. To navigate the collection returned, the parameters limit and offset can be set in the URI (for example: limit=10 & offset=0 ), as described in Paginated collections.

Two parameters are available to specify the information about subdomains and records to be returned by the List domain details call:

  • showRecords - if this parameter is set to true, then information

    out records is returned; if this parameter is set to false, then information about records is not returned.

  • showSubdomains - if this parameter is set to true, then information

    about subdomains is returned; if this parameter is set to false, then information about subdomains is not returned.

The following examples show the parameter settings to return information for both records and subdomains ( showSubdomains = true & showRecords = true ) for the List domain details call.

The examples also show the parameter settings to return basic information only, without records or subdomains ( showRecords = false & showSubdomains = false ) for the List domain details call.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

{domainId}

String

ID for the domain.

This table shows the query parameters for the request:

Name

Type

Description

showRecords

String

If showRecords is set to true, information about records is returned. If showRecords is set to false, information about records is not returned.

showSubdomains

String

If showSubdomains is set to true, information about subdomains is returned. If showSubdomains is set to false, information about subdomains is not returned.

This operation does not accept a request body.

Example List domain details with records, no subdomains: XML request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725233?showRecords=true&showSubdomains=false
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example List domain details with records, no subdomains: JSON request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725233?showRecords=true&showSubdomains=false
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Example List domain details with records and subdomains: XML request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725233?showRecords=true&showSubdomains=true
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example List domain details with records and subdomains: JSON request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725233?showRecords=true&showSubdomains=true
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Example List domain details, no records, no subdomains: XML request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725233?showRecords=false&showSubdomains=false
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example List domain details, no records, no subdomains: JSON request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725233?showRecords=false&showSubdomains=false
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Response#

Example List domain details with records, no subdomains: XML response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 1660

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain id="2725233" accountId="1234" name="example.com" ttl="3600" emailAddress="sample@rackspace.com" updated="2011-06-24T01:23:15Z" created="2011-06-24T01:12:51Z" comment="Optional domain comment..." xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <nameservers>
        <nameserver name="ns.rackspace.com"/>
        <nameserver name="ns2.rackspace.com"/>
    </nameservers>
    <recordsList totalEntries="6">
        <record id="A-6817754" type="A" name="ftp.example.com" data="192.0.2.8" ttl="5771" updated="2011-05-19T08:07:08-05:00" created="2011-05-18T14:53:09-05:00"/>
        <record id="A-6822994" type="A" name="example.com" data="192.0.2.17" ttl="86400" updated="2011-06-24T01:12:52Z" created="2011-06-24T01:12:52Z"/>
        <record id="NS-6251982" type="NS" name="example.com" data="ns.rackspace.com" ttl="3600" updated="2011-06-24T01:12:51Z" created="2011-06-24T01:12:51Z"/>
        <record id="NS-6251983" type="NS" name="example.com" data="ns2.rackspace.com" ttl="3600" updated="2011-06-24T01:12:51Z" created="2011-06-24T01:12:51Z"/>
        <record id="MX-3151218" type="MX" name="example.com" data="mail.example.com" ttl="3600" priority="5" updated="2011-06-24T01:12:53Z" created="2011-06-24T01:12:53Z"/>
        <record id="CNAME-9778009" type="CNAME" name="www.example.com" data="example.com" ttl="5400" updated="2011-06-24T01:12:54Z" created="2011-06-24T01:12:54Z" comment="This is a comment on the CNAME record"/>
    </recordsList>
</domain>

Example List domain details with records, no subdomains: JSON response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 1975

{
  "name" : "example.com",
  "id" : 2725233,
  "comment" : "Optional domain comment...",
  "updated" : "2011-06-24T01:23:15.000+0000",
  "nameservers" : [ {
    "name" : "ns.rackspace.com"
  }, {
    "name" : "ns2.rackspace.com"
  } ],
  "accountId" : 1234,
  "recordsList" : {
    "totalEntries" : 6,
    "records" : [ {
      "name" : "ftp.example.com",
      "id" : "A-6817754",
      "type" : "A",
      "data" : "192.0.2.8",
      "updated" : "2011-05-19T13:07:08.000+0000",
      "ttl" : 5771,
      "created" : "2011-05-18T19:53:09.000+0000"
    }, {
      "name" : "example.com",
      "id" : "A-6822994",
      "type" : "A",
      "data" : "192.0.2.17",
      "updated" : "2011-06-24T01:12:52.000+0000",
      "ttl" : 86400,
      "created" : "2011-06-24T01:12:52.000+0000"
    }, {
      "name" : "example.com",
      "id" : "NS-6251982",
      "type" : "NS",
      "data" : "ns.rackspace.com",
      "updated" : "2011-06-24T01:12:51.000+0000",
      "ttl" : 3600,
      "created" : "2011-06-24T01:12:51.000+0000"
    }, {
      "name" : "example.com",
      "id" : "NS-6251983",
      "type" : "NS",
      "data" : "ns2.rackspace.com",
      "updated" : "2011-06-24T01:12:51.000+0000",
      "ttl" : 3600,
      "created" : "2011-06-24T01:12:51.000+0000"
    }, {
      "name" : "example.com",
      "priority" : 5,
      "id" : "MX-3151218",
      "type" : "MX",
      "data" : "mail.example.com",
      "updated" : "2011-06-24T01:12:53.000+0000",
      "ttl" : 3600,
      "created" : "2011-06-24T01:12:53.000+0000"
    }, {
      "name" : "www.example.com",
      "id" : "CNAME-9778009",
      "type" : "CNAME",
      "comment" : "This is a comment on the CNAME record",
      "data" : "example.com",
      "updated" : "2011-06-24T01:12:54.000+0000",
      "ttl" : 5400,
      "created" : "2011-06-24T01:12:54.000+0000"
    } ]
  },
  "ttl" : 3600,
  "emailAddress" : "sample@rackspace.com",
  "created" : "2011-06-24T01:12:51.000+0000"
}

Example List domain details with records and subdomains: XML response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 2421

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain id="2725233" accountId="1234" name="example.com" ttl="3600" emailAddress="sample@rackspace.com" updated="2011-06-24T01:23:15Z" created="2011-06-24T01:12:51Z" comment="Optional domain comment..." xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <nameservers>
        <nameserver name="ns.rackspace.com"/>
        <nameserver name="ns2.rackspace.com"/>
    </nameservers>
    <recordsList totalEntries="6">
        <record id="A-6817754" type="A" name="ftp.example.com" data="192.0.2.8" ttl="5771" updated="2011-05-19T08:07:08-05:00" created="2011-05-18T14:53:09-05:00"/>
        <record id="A-6822994" type="A" name="example.com" data="192.0.2.17" ttl="86400" updated="2011-06-24T01:12:52Z" created="2011-06-24T01:12:52Z"/>
        <record id="NS-6251982" type="NS" name="example.com" data="ns.rackspace.com" ttl="3600" updated="2011-06-24T01:12:51Z" created="2011-06-24T01:12:51Z"/>
        <record id="NS-6251983" type="NS" name="example.com" data="ns2.rackspace.com" ttl="3600" updated="2011-06-24T01:12:51Z" created="2011-06-24T01:12:51Z"/>
        <record id="MX-3151218" type="MX" name="example.com" data="mail.example.com" ttl="3600" priority="5" updated="2011-06-24T01:12:53Z" created="2011-06-24T01:12:53Z"/>
        <record id="CNAME-9778009" type="CNAME" name="www.example.com" data="example.com" ttl="5400" updated="2011-06-24T01:12:54Z" created="2011-06-24T01:12:54Z" comment="This is a comment on the CNAME record"/>
    </recordsList>
    <subdomains totalEntries="4">
        <domain id="2725257" name="sub1.example.com" emailAddress="sample@rackspace.com" updated="2011-06-23T03:09:34Z" created="2011-06-23T03:09:33Z" comment="1st sample subdomain"/>
        <domain id="2725258" name="sub2.example.com" emailAddress="sample@rackspace.com" updated="2011-06-23T03:52:55Z" created="2011-06-23T03:52:55Z" comment="1st sample subdomain"/>
        <domain id="2725260" name="north.example.com" emailAddress="sample@rackspace.com" updated="2011-06-23T03:53:10Z" created="2011-06-23T03:53:09Z"/>
        <domain id="2725261" name="south.example.com" emailAddress="sample@rackspace.com" updated="2011-06-23T03:53:14Z" created="2011-06-23T03:53:14Z" comment="Final sample subdomain"/>
    </subdomains>
</domain>

Example List domain details with records and subdomains: JSON response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 3020

{
  "name" : "example.com",
  "id" : 2725233,
  "comment" : "Optional domain comment...",
  "updated" : "2011-06-24T01:23:15.000+0000",
  "nameservers" : [ {
    "name" : "ns.rackspace.com"
  }, {
    "name" : "ns2.rackspace.com"
  } ],
  "accountId" : 1234,
  "recordsList" : {
    "totalEntries" : 6,
    "records" : [ {
      "name" : "ftp.example.com",
      "id" : "A-6817754",
      "type" : "A",
      "data" : "192.0.2.8",
      "updated" : "2011-05-19T13:07:08.000+0000",
      "ttl" : 5771,
      "created" : "2011-05-18T19:53:09.000+0000"
    }, {
      "name" : "example.com",
      "id" : "A-6822994",
      "type" : "A",
      "data" : "192.0.2.17",
      "updated" : "2011-06-24T01:12:52.000+0000",
      "ttl" : 86400,
      "created" : "2011-06-24T01:12:52.000+0000"
    }, {
      "name" : "example.com",
      "id" : "NS-6251982",
      "type" : "NS",
      "data" : "ns.rackspace.com",
      "updated" : "2011-06-24T01:12:51.000+0000",
      "ttl" : 3600,
      "created" : "2011-06-24T01:12:51.000+0000"
    }, {
      "name" : "example.com",
      "id" : "NS-6251983",
      "type" : "NS",
      "data" : "ns2.rackspace.com",
      "updated" : "2011-06-24T01:12:51.000+0000",
      "ttl" : 3600,
      "created" : "2011-06-24T01:12:51.000+0000"
    }, {
      "name" : "example.com",
      "priority" : 5,
      "id" : "MX-3151218",
      "type" : "MX",
      "data" : "mail.example.com",
      "updated" : "2011-06-24T01:12:53.000+0000",
      "ttl" : 3600,
      "created" : "2011-06-24T01:12:53.000+0000"
    }, {
      "name" : "www.example.com",
      "id" : "CNAME-9778009",
      "type" : "CNAME",
      "comment" : "This is a comment on the CNAME record",
      "data" : "example.com",
      "updated" : "2011-06-24T01:12:54.000+0000",
      "ttl" : 5400,
      "created" : "2011-06-24T01:12:54.000+0000"
    } ]
  },
  "subdomains" : {
    "domains" : [ {
      "name" : "sub1.example.com",
      "id" : 2725257,
      "comment" : "1st sample subdomain",
      "updated" : "2011-06-23T03:09:34.000+0000",
      "emailAddress" : "sample@rackspace.com",
      "created" : "2011-06-23T03:09:33.000+0000"
    }, {
      "name" : "sub2.example.com",
      "id" : 2725258,
      "comment" : "1st sample subdomain",
      "updated" : "2011-06-23T03:52:55.000+0000",
      "emailAddress" : "sample@rackspace.com",
      "created" : "2011-06-23T03:52:55.000+0000"
    }, {
      "name" : "north.example.com",
      "id" : 2725260,
      "updated" : "2011-06-23T03:53:10.000+0000",
      "emailAddress" : "sample@rackspace.com",
      "created" : "2011-06-23T03:53:09.000+0000"
    }, {
      "name" : "south.example.com",
      "id" : 2725261,
      "comment" : "Final sample subdomain",
      "updated" : "2011-06-23T03:53:14.000+0000",
      "emailAddress" : "sample@rackspace.com",
      "created" : "2011-06-23T03:53:14.000+0000"
    } ],
    "totalEntries" : 4
  },
  "ttl" : 3600,
  "emailAddress" : "sample@rackspace.com",
  "created" : "2011-06-24T01:12:51.000+0000"
}

Example List domain details, no records, no subdomains: XML response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 570

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain id="2725233" accountId="1234" name="example.com" ttl="3600" emailAddress="sample@rackspace.com" updated="2011-06-24T01:23:15Z" created="2011-06-24T01:12:51Z" comment="Optional domain comment..." xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <nameservers>
        <nameserver name="ns.rackspace.com"/>
        <nameserver name="ns2.rackspace.com"/>
    </nameservers>
</domain>

Example List domain details, no records, no subdomains: JSON response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 375

{
  "name" : "example.com",
  "id" : 2725233,
  "comment" : "Optional domain comment...",
  "updated" : "2011-06-24T01:23:15.000+0000",
  "nameservers" : [ {
    "name" : "ns.rackspace.com"
  }, {
    "name" : "ns2.rackspace.com"
  } ],
  "accountId" : 1234,
  "ttl" : 3600,
  "emailAddress" : "sample@rackspace.com",
  "created" : "2011-06-24T01:12:51.000+0000"
}

Update domain#

PUT /v1.0/{account}/domains/{domainId}

Updates the configuration of a domain.

Note

This call returns an asynchronous response. Refer to Synchronous and asynchronous responses for more details and examples of the way that asynchronous responses work.

This call modifies DNS domain(s) attributes only. records cannot be added, modified, or Deleted. Only the TTL, email address and comment attributes of a domain can be modified.

If a request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response will be returned with information regarding the nature of the failure in the body of the response. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST the request again.

Note

  • Refer to the section “DNS Propagation” in the Devguide for information about DNS propagation.

  • A domain’s id is immutable.

  • When the domain or record TTL is supplied by the user, either via a create or update call, the TTL values must be 300 seconds or more.

  • name cannot be specified, because the domain name cannot be modified.

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Accepted

Request is accepted.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String

Arbitrary character string generated by the authentication service in response to valid credentials.

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

{domainId}

String

ID for the domain.

This table shows the body parameters for the request:

Name

Type

Description

id

String

For modifying multiple domains, the id for each domain must be specified as an attribute. Note that for modifying a single domain, the id is a required parameter at the end of the API call URI.

emailAddress

String (Optional)

Email address to use for contacting the domain administrator.

ttl

String (Optional)

If specified, must be greater than or equal to 300.

comment

String (Optional)

If included, its length must be less than or equal to 160 characters.

Example Update domain: XML request

PUT https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725233
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 309

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain ttl="3600" emailAddress="sample@rackspace.com" comment="Optional domain comment..." xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0"/>

Example Update domain: JSON request

PUT https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725233
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 105

{
  "comment" : "Optional domain comment...",
  "ttl" : 3600,
  "emailAddress" : "sample@rackspace.com"
}

Response#

This operation does not return a response body.

Delete domain#

DELETE /v1.0/{account}/domains/{domainId}

Deletes a domain from an account.

Note

This call returns an asynchronous response, as described in Synchronous and asynchronous responses.

This call deletes one or more specified domains from the account; when a domain is deleted, its immediate resource records are also deleted from the account. By default, if a deleted domain had subdomains, each subdomain becomes a root domain and is not deleted; this can be overridden by the optional deleteSubdomains parameter. Utilizing the optional deleteSubdomains parameter on domains without subdomains does not result in a failure. When a domain is deleted, any and all domain data is immediately purged and is not recoverable via the API. So on a successful delete, subsequent requests for the deleted object should return itemNotFound ( 404 ).

Transactionally, delete calls behave differently than other calls in that deletes are never rolled back on exceptions, and multiple deletes in the same request do not fail as a group. Instead, each delete is attempted even if one or more fail. The response for a delete request in which one or more items fail contains information regarding which items failed as well as information regarding specific issues that caused the failure(s). See the examples that follow.

In the previous two response examples, the requested domain objects could not be deleted, because they were not found.

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Accepted

Request is accepted.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String

Arbitrary character string generated by the authentication service in response to valid credentials.

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

{domainId}

String

ID for the domain.

This operation does not accept a request body.

Example Delete domain: XML request

DELETE https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725260
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example Delete domain: JSON request

DELETE https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725260
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Response#

This operation does not return a response body.

Delete domain and its subdomains#

DELETE /v1.0/{account}/domains/{domainId}

Deletes a domain and its subdomains from an account.

Note

This call returns an asynchronous response, as described in Synchronous and asynchronous responses.

This call deletes one or more specified domains from the account; when a domain is deleted, its immediate resource records are also deleted from the account. By default, if a deleted domain had subdomains, each subdomain becomes a root domain and is not deleted; this can be overridden by the optional deleteSubdomains parameter. Utilizing the optional deleteSubdomains parameter on domains without subdomains does not result in a failure. When a domain is deleted, any and all domain data is immediately purged and is not recoverable via the API. So on a successful delete, subsequent requests for the deleted object should return itemNotFound ( 404 ).

Transactionally, delete calls behave differently than other calls in that deletes are never rolled back on exceptions, and multiple deletes in the same request do not fail as a group. Instead, each delete is attempted even if one or more fail. The response for a delete request in which one or more items fail contains information regarding which items failed as well as information regarding specific issues that caused the failure(s). See the examples that follow.

In the previous two response examples, the requested domain objects could not be deleted, because they were not found.

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Accepted

Request is accepted.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

{domainId}

String

ID for the domain.

This table shows the query parameters for the request:

Name

Type

Description

deleteSubdomains

String

If deleteSubdomains is true, also deletes subdomains. If false, subdomains are not deleted.

This operation does not accept a request body.

Example Delete domain and subdomains: XML request

DELETE https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725260?deleteSubdomains=true
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example Delete domain and subdomains: JSON request

DELETE https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725260?deleteSubdomains=true
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Response#

This operation does not return a response body.

Show domain changes#

GET /v1.0/{account}/domains/{domainId}/changes

Shows all changes to a specified domain since a specified date/time.

This call shows all changes to a specified domain since a specified date/time. The since parameter is optional and defaults to midnight of the current day. See Date/Time format for details on how to specify this parameter’s value.

The examples below show the requests and corresponding responses to list the domain changes since midnight, GMT-5, on September 13, 2011.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

{domainId}

String

ID for the domain.

This table shows the query parameters for the request:

Name

Type

Description

since

String

The Date/Time from which the domain changes should be shown.

This operation does not accept a request body.

Example List domain Changes: XML request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/45678/changes?since=2011-09-13T00:00:00-0500
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example List domain Changes: JSON request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/45678/changes?since=2011-09-13T00:00:00-0500
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Response#

Example List domain Changes: XML response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 2460

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<changes totalEntries="4" from="2011-09-13T00:00:00-05:00" to="2011-09-19T16:36:01-05:00" xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <change accountId="1234" domain="rs.example.com" targetId="45678" targetType="Domain" action="update">
        <changeDetail field="serial_number" originalValue="1315927395" newValue="1315930302"/>
        <changeDetail field="updated_at" originalValue="Tue Sep 13 15:23:15 UTC 2011" newValue="Tue Sep 13 16:11:42 UTC 2011"/>
    </change>
    <change domain="rs.example.com" targetId="222222" targetType="MX Record" action="create">
        <changeDetail field="created_at" originalValue="" newValue="Tue Sep 13 16:11:42 UTC 2011"/>
        <changeDetail field="ttl" originalValue="" newValue="3600"/>
        <changeDetail field="fqdn" originalValue="" newValue="rs.example.com"/>
        <changeDetail field="updated_at" originalValue="" newValue="Tue Sep 13 16:11:42 UTC 2011"/>
        <changeDetail field="destination" originalValue="" newValue="mail.rs.example.com"/>
        <changeDetail field="priority" originalValue="" newValue="1"/>
        <changeDetail field="id" originalValue="" newValue="222222"/>
        <changeDetail field="zone_id" originalValue="" newValue="45678"/>
    </change>
    <change accountId="1234" domain="rs.example.com" targetId="45678" targetType="Domain" action="update">
        <changeDetail field="serial_number" originalValue="1310656481" newValue="1315927395"/>
        <changeDetail field="updated_at" originalValue="Thu Jul 14 15:14:41 UTC 2011" newValue="Tue Sep 13 15:23:15 UTC 2011"/>
    </change>
    <change domain="rs.example.com" targetId="87654" targetType="CNAME Record" action="create">
        <changeDetail field="created_at" originalValue="" newValue="Tue Sep 13 15:23:15 UTC 2011"/>
        <changeDetail field="ttl" originalValue="" newValue="3600"/>
        <changeDetail field="fqdn" originalValue="" newValue="*.rs.example.com"/>
        <changeDetail field="updated_at" originalValue="" newValue="Tue Sep 13 15:23:15 UTC 2011"/>
        <changeDetail field="destination" originalValue="" newValue="rs.example.com"/>
        <changeDetail field="id" originalValue="" newValue="87654"/>
        <changeDetail field="zone_id" originalValue="" newValue="45678"/>
    </change>
</changes>

Example List domain Changes: JSON response

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 2762

{
  "from" : "2011-09-13T05:00:00.000+0000",
  "to" : "2011-09-19T21:36:01.000+0000",
  "totalEntries" : 4,
  "changes" : [ {
    "domain" : "rs.example.com",
    "targetType" : "Domain",
    "action" : "update",
    "changeDetails" : [ {
      "field" : "serial_number",
      "newValue" : "1315930302",
      "originalValue" : "1315927395"
    }, {
      "field" : "updated_at",
      "newValue" : "Tue Sep 13 16:11:42 UTC 2011",
      "originalValue" : "Tue Sep 13 15:23:15 UTC 2011"
    } ],
    "accountId" : 1234,
    "targetId" : 45678
  }, {
    "domain" : "rs.example.com",
    "targetType" : "MX Record",
    "action" : "create",
    "changeDetails" : [ {
      "field" : "created_at",
      "newValue" : "Tue Sep 13 16:11:42 UTC 2011",
      "originalValue" : ""
    }, {
      "field" : "ttl",
      "newValue" : "3600",
      "originalValue" : ""
    }, {
      "field" : "fqdn",
      "newValue" : "rs.example.com",
      "originalValue" : ""
    }, {
      "field" : "updated_at",
      "newValue" : "Tue Sep 13 16:11:42 UTC 2011",
      "originalValue" : ""
    }, {
      "field" : "destination",
      "newValue" : "mail.rs.example.com",
      "originalValue" : ""
    }, {
      "field" : "priority",
      "newValue" : "1",
      "originalValue" : ""
    }, {
      "field" : "id",
      "newValue" : "222222",
      "originalValue" : ""
    }, {
      "field" : "zone_id",
      "newValue" : "45678",
      "originalValue" : ""
    } ],
    "targetId" : 222222
  }, {
    "domain" : "rs.example.com",
    "targetType" : "Domain",
    "action" : "update",
    "changeDetails" : [ {
      "field" : "serial_number",
      "newValue" : "1315927395",
      "originalValue" : "1310656481"
    }, {
      "field" : "updated_at",
      "newValue" : "Tue Sep 13 15:23:15 UTC 2011",
      "originalValue" : "Thu Jul 14 15:14:41 UTC 2011"
    } ],
    "accountId" : 1234,
    "targetId" : 45678
  }, {
    "domain" : "rs.example.com",
    "targetType" : "CNAME Record",
    "action" : "create",
    "changeDetails" : [ {
      "field" : "created_at",
      "newValue" : "Tue Sep 13 15:23:15 UTC 2011",
      "originalValue" : ""
    }, {
      "field" : "ttl",
      "newValue" : "3600",
      "originalValue" : ""
    }, {
      "field" : "fqdn",
      "newValue" : "*.rs.example.com",
      "originalValue" : ""
    }, {
      "field" : "updated_at",
      "newValue" : "Tue Sep 13 15:23:15 UTC 2011",
      "originalValue" : ""
    }, {
      "field" : "destination",
      "newValue" : "rs.example.com",
      "originalValue" : ""
    }, {
      "field" : "id",
      "newValue" : "87654",
      "originalValue" : ""
    }, {
      "field" : "zone_id",
      "newValue" : "45678",
      "originalValue" : ""
    } ],
    "targetId" : 87654
  } ]
}

Export domain#

GET /v1.0/{account}/domains/{domainId}/export

Exports details for a specified domain.

Note

This call returns an asynchronous response. Refer to Synchronous and asynchronous responses.

This call provides the BIND (Berkeley Internet Name Domain) 9 formatted contents of the requested domain. This call is for a single domain only, and as such, does not traverse up or down the domain hierarchy for details (that is, no subdomain information is provided).

Note

  • This call is not capable of returning anything for a domain that has been deleted.

  • The BIND 9 formatted contents of the requested domain will have no comments listed for the domain or for the records of the domain being exported.

  • If there are more than 300 records in the Export domain operation, records are dropped from the export due to a known defect. Please contact your support team to perform the export for you.

  • The following examples show the final successful response for the asynchronous call.

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Accepted

Request is accepted.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String

Arbitrary character string generated by the authentication service in response to valid credentials.

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

{domainId}

String

ID for the domain.

This operation does not accept a request body.

Example Export domain: XML request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725339/export
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example Export domain: JSON request

GET https://dns.api.rackspacecloud.com/v1.0/1234/domains/2725339/export
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Response#

Example Export domain: XML response

Status: 202 Accepted
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 665

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain id="2725339" accountId="1234" contentType="BIND_9" xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <contents>
             example.net. 3600 IN SOA ns.rackspace.com.
                     sample@rackspace.com. 1308874739 3600 3600 3600 3600
                     example.net. 86400 IN A 110.11.12.16
                     example.net. 3600 IN MX 5 mail2.example.net.
                     www.example.net. 5400 IN CNAME example.net.
                     example.net. 5600 IN NS ns.rackspace.com.
                     example.net. 5600 IN NS ns2.rackspace.com.
             </contents>
</domain>

Example Export domain: JSON response

Status: 202 Accepted
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 476

{
  "id" : 2725339,
  "contentType" : "BIND_9",
  "contents" : "\n    \t\texample.net. 3600 IN SOA ns.rackspace.com.\n\t\t\tsample@rackspace.com. 1308874739 3600 3600 3600 3600\n\t\t\texample.net. 86400 IN A 110.11.12.16\n\t\t\texample.net. 3600 IN MX 5 mail2.example.net.\n\t\t\twww.example.net. 5400 IN CNAME example.net.\n\t\t\texample.net. 5600 IN NS ns.rackspace.com.\n\t\t\texample.net. 5600 IN NS ns2.rackspace.com.\t\t\t\n\t\t",
  "accountId" : 1234
}

Clone domain#

POST /v1.0/{account}/domains/{domainId}/clone

Clones a domain.

Creates a specified domain ( example2.com ) by cloning a domain with id domainId. All options except cloneName assume a default value of true.

Note

This call returns an asynchronous response, as described in Synchronous and asynchronous responses. The AsyncResponse returned will be similar to that returned for Create domain but with the request element absent because the clone request has no body.

This call duplicates a single existing domain configuration with a new domain name for a specified Cloud account. By default, all records and, optionally, subdomain(s) are duplicated as well. Both the existing domain (referred to as the reference domain) and the new cloned domain must exist under the same Cloud account.

See the query parameters table for the parameters and options available to specify how the cloning affects subdomains, comments, email addresses, and record data.

Note

  • If the corresponding request cannot be fulfilled due to insufficient or invalid data, or if the reference domain does not exist, an HTTP 400 (Bad Request) error response will be returned in the body of the response with information regarding the nature of the failure.

  • Clone domain is an atomic operation. If there is a failure in the duplication of a single record or subdomain, the entire process will fail. Failures are non-recoverable and require the caller to correct the cause of the failure and POST the request again.

  • The Clone domain operation is currently supported for domains under a given Cloud account. The cloned domain must belong to the same account as the reference domain.

  • The Clone domain operation will return an exception if the operation would result in creating a domain that already exists. The exception would indicate that the domain already exists.

  • The Clone domain operation may take slightly longer to complete than a comparable Create domain request.

  • PTR records (for Reverse DNS) are not represented when a domain is created and, therefore, are not included when a domain is cloned.

  • If your reference domain already has both default Rackspace Nameserver (NS) records, the cloned domain will be created with no additional default Rackspace NS records. If your reference domain lacks one or both of the default Rackspace NS records, the cloned domain will be created with additional Rackspace default NS records to make a total of two default Rackspace NS records. If the presence of default Rackspace NS records is not your preference, they can be deleted from the cloned domain as long as at least one NS record remains (Rackspace or non-Rackspace).

  • Any non-default (non-Rackspace) NS records in the reference domain are cloned and modified in a way that is consistent with all other record types.

According to the cloneName specified, the domain name and record name(s) will automatically be modified and replaced in the new cloned domain as part of the cloning process and cannot be influenced by any request options. See the table below for the parameters and options available to specify how the cloning affects subdomains, comments, email addresses, and record data.

The following examples show the Clone domain requests.

Note

The following examples show the initial 202 Accepted response for the asynchronous call and indicate that the task has been accepted for processing.

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Accepted

Request is accepted.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

409

Already Exists

The item already exists.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

{domainId}

String

ID for the domain.

This table shows the query parameters for the request:

Name

Type

Description

cloneName

String

The name of the new (cloned) domain.

cloneSubdomains

String (Optional)

Recursively clone subdomains. Defaults to true. If set to false, then only the top level domain and its records are cloned. Cloned subdomain configurations are modified the same way that cloned top level domain configurations are modified.

modifyRecordData

String (Optional)

Replaces occurrences of the reference domain name with the new domain name in data fields (of records) on the cloned (new) domain. Does not affect NS records. Defaults to true.

modifyEmailAddress

String (Optional)

Replaces occurrences of the reference domain name with the new domain name in email addresses on the cloned (new) domain. Defaults to true.

modifyComment

String (Optional)

Replaces occurrences of the reference domain name with the new domain name in comments on the cloned (new) domain. Defaults to true.

This operation does not accept a request body.

Example Clone domain: XML request

POST https://dns.api.rackspacecloud.com/v1.0/1234/domains/3586209/clone?cloneName=clone1.com
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example Clone domain: JSON request

POST https://dns.api.rackspacecloud.com/v1.0/1234/domains/3586209/clone?cloneName=clone1.com
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

Response#

Example Initial (202) Clone domain: XML response

Status: 202 Accepted
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 592

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<asyncresponse xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <jobId>52179628-6df6-46a0-bdb3-078769cd0e9d</jobId>
    <callbackUrl>https://dns.api.rackspacecloud.com/v1.0/1234/status/52179628-6df6-46a0-bdb3-078769cd0e9d</callbackUrl>
    <status>RUNNING</status>
    <requestUrl>https://dns.api.rackspacecloud.com/v1.0/1234/domains/3586209/clone?cloneName=clone1.com</requestUrl>
    <verb>POST</verb>
</asyncresponse>

Example Initial (202) Clone domain: JSON response

Status: 202 Accepted
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 315

{
  "status" : "RUNNING",
  "verb" : "POST",
  "jobId" : "52179628-6df6-46a0-bdb3-078769cd0e9d",
  "callbackUrl" : "https://dns.api.rackspacecloud.com/v1.0/1234/status/52179628-6df6-46a0-bdb3-078769cd0e9d",
  "requestUrl" : "https://dns.api.rackspacecloud.com/v1.0/1234/domains/3586209/clone?cloneName=clone1.com"
}

The following are examples of the reference domain and the resulting cloned domain:

Example Reference (Existing) domain cloner.com: XML

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 2804

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain id="3586209" accountId="1234" name="cloner.com" ttl="7788" emailAddress="owner@cloner.com" updated="2013-05-06T12:10:55-05:00" created="2013-05-06T12:10:51-05:00" comment="cloner.com is a template domain for cloning others. cloner.com has subdomains - sub1.cloner.com, sub2.cloner.com, sub3.cloner.com" xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <nameservers>
        <nameserver name="ns.rackspace.com"/>
        <nameserver name="ns2.rackspace.com"/>
    </nameservers>
    <recordsList totalEntries="7">
        <record id="A-9516802" type="A" name="ftp.cloner.com" data="192.0.2.8" ttl="5771" updated="2013-05-06T12:10:52-05:00" created="2013-05-06T12:10:52-05:00"/>
        <record id="A-9516803" type="A" name="cloner.com" data="192.0.2.17" ttl="86400" updated="2013-05-06T12:10:52-05:00" created="2013-05-06T12:10:52-05:00"/>
        <record id="NS-8504404" type="NS" name="cloner.com" data="ns.rackspace.com" ttl="7788" updated="2013-05-06T12:10:51-05:00" created="2013-05-06T12:10:51-05:00"/>
        <record id="NS-8504405" type="NS" name="cloner.com" data="ns2.rackspace.com" ttl="7788" updated="2013-05-06T12:10:51-05:00" created="2013-05-06T12:10:51-05:00"/>
        <record id="NS-8504406" type="NS" name="cloner.com" data="server1.cloner.com" ttl="3600" updated="2013-05-06T12:10:53-05:00" created="2013-05-06T12:10:53-05:00"/>
        <record id="MX-4220031" type="MX" name="cloner.com" data="mail.cloner.com" ttl="3600" priority="5" updated="2013-05-06T12:10:54-05:00" created="2013-05-06T12:10:54-05:00"/>
        <record id="CNAME-11336151" type="CNAME" name="www.cloner.com" data="cloner.com" ttl="5400" updated="2013-05-06T12:10:55-05:00" created="2013-05-06T12:10:55-05:00" comment="This is a comment on the CNAME record"/>
    </recordsList>
    <subdomains totalEntries="3">
        <domain id="3586210" name="sub1.cloner.com" emailAddress="administrator@rackspace.com" updated="2013-05-06T12:10:56-05:00" created="2013-05-06T12:10:55-05:00" comment="sub1.cloner.com uses rackspace.com for email domain name. Sister subdomains are sub2.cloner.com, sub3.cloner.com"/>
        <domain id="3586211" name="sub2.cloner.com" emailAddress="admin@cloner.com" updated="2013-05-06T12:10:56-05:00" created="2013-05-06T12:10:56-05:00" comment="sub1.cloner.com uses parent domain name, cloner.com, for email domain name"/>
        <domain id="3586212" name="sub3.cloner.com" emailAddress="adm@sub3.cloner.com" updated="2013-05-06T12:10:57-05:00" created="2013-05-06T12:10:57-05:00" comment="sub3.cloner.com uses it's own domain name for email domain name"/>
    </subdomains>
</domain>

Example Resulting (Cloned) domain clone1.com: XML

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 2804

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain id="3586213" accountId="1234" name="clone1.com" ttl="7788" emailAddress="owner@clone1.com" updated="2013-05-06T12:17:35-05:00" created="2013-05-06T12:17:31-05:00" comment="clone1.com is a template domain for cloning others. clone1.com has subdomains - sub1.clone1.com, sub2.clone1.com, sub3.clone1.com" xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <nameservers>
        <nameserver name="ns.rackspace.com"/>
        <nameserver name="ns2.rackspace.com"/>
    </nameservers>
    <recordsList totalEntries="7">
        <record id="A-9516805" type="A" name="ftp.clone1.com" data="192.0.2.8" ttl="5771" updated="2013-05-06T12:17:32-05:00" created="2013-05-06T12:17:32-05:00"/>
        <record id="A-9516806" type="A" name="clone1.com" data="192.0.2.17" ttl="86400" updated="2013-05-06T12:17:33-05:00" created="2013-05-06T12:17:33-05:00"/>
        <record id="NS-8504413" type="NS" name="clone1.com" data="ns.rackspace.com" ttl="7788" updated="2013-05-06T12:17:31-05:00" created="2013-05-06T12:17:31-05:00"/>
        <record id="NS-8504414" type="NS" name="clone1.com" data="ns2.rackspace.com" ttl="7788" updated="2013-05-06T12:17:31-05:00" created="2013-05-06T12:17:31-05:00"/>
        <record id="NS-8504415" type="NS" name="clone1.com" data="server1.clone1.com" ttl="3600" updated="2013-05-06T12:17:34-05:00" created="2013-05-06T12:17:34-05:00"/>
        <record id="MX-4220032" type="MX" name="clone1.com" data="mail.clone1.com" ttl="3600" priority="5" updated="2013-05-06T12:17:35-05:00" created="2013-05-06T12:17:35-05:00"/>
        <record id="CNAME-11336152" type="CNAME" name="www.clone1.com" data="clone1.com" ttl="5400" updated="2013-05-06T12:17:35-05:00" created="2013-05-06T12:17:35-05:00" comment="This is a comment on the CNAME record"/>
    </recordsList>
    <subdomains totalEntries="3">
        <domain id="3586214" name="sub1.clone1.com" emailAddress="administrator@rackspace.com" updated="2013-05-06T12:17:36-05:00" created="2013-05-06T12:17:36-05:00" comment="sub1.clone1.com uses rackspace.com for email domain name. Sister subdomains are sub2.clone1.com, sub3.clone1.com"/>
        <domain id="3586215" name="sub2.clone1.com" emailAddress="admin@clone1.com" updated="2013-05-06T12:17:37-05:00" created="2013-05-06T12:17:37-05:00" comment="sub1.clone1.com uses parent domain name, clone1.com, for email domain name"/>
        <domain id="3586216" name="sub3.clone1.com" emailAddress="adm@sub3.clone1.com" updated="2013-05-06T12:17:37-05:00" created="2013-05-06T12:17:37-05:00" comment="sub3.clone1.com uses it's own domain name for email domain name"/>
    </subdomains>
</domain>

Example Reference (Existing) domain cloner.com: JSON

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 3325

{
  "name" : "cloner.com",
  "id" : 3586209,
  "comment" : "cloner.com is a template domain for cloning others. cloner.com has subdomains - sub1.cloner.com, sub2.cloner.com, sub3.cloner.com",
  "updated" : "2013-05-06T17:10:55.000+0000",
  "nameservers" : [ {
    "name" : "ns.rackspace.com"
  }, {
    "name" : "ns2.rackspace.com"
  } ],
  "accountId" : 1234,
  "recordsList" : {
    "totalEntries" : 7,
    "records" : [ {
      "name" : "ftp.cloner.com",
      "id" : "A-9516802",
      "type" : "A",
      "data" : "192.0.2.8",
      "updated" : "2013-05-06T17:10:52.000+0000",
      "ttl" : 5771,
      "created" : "2013-05-06T17:10:52.000+0000"
    }, {
      "name" : "cloner.com",
      "id" : "A-9516803",
      "type" : "A",
      "data" : "192.0.2.17",
      "updated" : "2013-05-06T17:10:52.000+0000",
      "ttl" : 86400,
      "created" : "2013-05-06T17:10:52.000+0000"
    }, {
      "name" : "cloner.com",
      "id" : "NS-8504404",
      "type" : "NS",
      "data" : "ns.rackspace.com",
      "updated" : "2013-05-06T17:10:51.000+0000",
      "ttl" : 7788,
      "created" : "2013-05-06T17:10:51.000+0000"
    }, {
      "name" : "cloner.com",
      "id" : "NS-8504405",
      "type" : "NS",
      "data" : "ns2.rackspace.com",
      "updated" : "2013-05-06T17:10:51.000+0000",
      "ttl" : 7788,
      "created" : "2013-05-06T17:10:51.000+0000"
    }, {
      "name" : "cloner.com",
      "id" : "NS-8504406",
      "type" : "NS",
      "data" : "server1.cloner.com",
      "updated" : "2013-05-06T17:10:53.000+0000",
      "ttl" : 3600,
      "created" : "2013-05-06T17:10:53.000+0000"
    }, {
      "name" : "cloner.com",
      "priority" : 5,
      "id" : "MX-4220031",
      "type" : "MX",
      "data" : "mail.cloner.com",
      "updated" : "2013-05-06T17:10:54.000+0000",
      "ttl" : 3600,
      "created" : "2013-05-06T17:10:54.000+0000"
    }, {
      "name" : "www.cloner.com",
      "id" : "CNAME-11336151",
      "type" : "CNAME",
      "comment" : "This is a comment on the CNAME record",
      "data" : "cloner.com",
      "updated" : "2013-05-06T17:10:55.000+0000",
      "ttl" : 5400,
      "created" : "2013-05-06T17:10:55.000+0000"
    } ]
  },
  "subdomains" : {
    "domains" : [ {
      "name" : "sub1.cloner.com",
      "id" : 3586210,
      "comment" : "sub1.cloner.com uses rackspace.com for email domain name. Sister subdomains are sub2.cloner.com, sub3.cloner.com",
      "updated" : "2013-05-06T17:10:56.000+0000",
      "emailAddress" : "administrator@rackspace.com",
      "created" : "2013-05-06T17:10:55.000+0000"
    }, {
      "name" : "sub2.cloner.com",
      "id" : 3586211,
      "comment" : "sub1.cloner.com uses parent domain name, cloner.com, for email domain name",
      "updated" : "2013-05-06T17:10:56.000+0000",
      "emailAddress" : "admin@cloner.com",
      "created" : "2013-05-06T17:10:56.000+0000"
    }, {
      "name" : "sub3.cloner.com",
      "id" : 3586212,
      "comment" : "sub3.cloner.com uses it's own domain name for email domain name",
      "updated" : "2013-05-06T17:10:57.000+0000",
      "emailAddress" : "adm@sub3.cloner.com",
      "created" : "2013-05-06T17:10:57.000+0000"
    } ],
    "totalEntries" : 3
  },
  "ttl" : 7788,
  "emailAddress" : "owner@cloner.com",
  "created" : "2013-05-06T17:10:51.000+0000"
}

Example Resulting (Cloned) domain clone1.com: JSON

Status: 200 OK
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 3325

{
  "name" : "clone1.com",
  "id" : 3586213,
  "comment" : "clone1.com is a template domain for cloning others. clone1.com has subdomains - sub1.clone1.com, sub2.clone1.com, sub3.clone1.com",
  "updated" : "2013-05-06T17:17:35.000+0000",
  "nameservers" : [ {
    "name" : "ns.rackspace.com"
  }, {
    "name" : "ns2.rackspace.com"
  } ],
  "accountId" : 1234,
  "recordsList" : {
    "totalEntries" : 7,
    "records" : [ {
      "name" : "ftp.clone1.com",
      "id" : "A-9516805",
      "type" : "A",
      "data" : "192.0.2.8",
      "updated" : "2013-05-06T17:17:32.000+0000",
      "ttl" : 5771,
      "created" : "2013-05-06T17:17:32.000+0000"
    }, {
      "name" : "clone1.com",
      "id" : "A-9516806",
      "type" : "A",
      "data" : "192.0.2.17",
      "updated" : "2013-05-06T17:17:33.000+0000",
      "ttl" : 86400,
      "created" : "2013-05-06T17:17:33.000+0000"
    }, {
      "name" : "clone1.com",
      "id" : "NS-8504413",
      "type" : "NS",
      "data" : "ns.rackspace.com",
      "updated" : "2013-05-06T17:17:31.000+0000",
      "ttl" : 7788,
      "created" : "2013-05-06T17:17:31.000+0000"
    }, {
      "name" : "clone1.com",
      "id" : "NS-8504414",
      "type" : "NS",
      "data" : "ns2.rackspace.com",
      "updated" : "2013-05-06T17:17:31.000+0000",
      "ttl" : 7788,
      "created" : "2013-05-06T17:17:31.000+0000"
    }, {
      "name" : "clone1.com",
      "id" : "NS-8504415",
      "type" : "NS",
      "data" : "server1.clone1.com",
      "updated" : "2013-05-06T17:17:34.000+0000",
      "ttl" : 3600,
      "created" : "2013-05-06T17:17:34.000+0000"
    }, {
      "name" : "clone1.com",
      "priority" : 5,
      "id" : "MX-4220032",
      "type" : "MX",
      "data" : "mail.clone1.com",
      "updated" : "2013-05-06T17:17:35.000+0000",
      "ttl" : 3600,
      "created" : "2013-05-06T17:17:35.000+0000"
    }, {
      "name" : "www.clone1.com",
      "id" : "CNAME-11336152",
      "type" : "CNAME",
      "comment" : "This is a comment on the CNAME record",
      "data" : "clone1.com",
      "updated" : "2013-05-06T17:17:35.000+0000",
      "ttl" : 5400,
      "created" : "2013-05-06T17:17:35.000+0000"
    } ]
  },
  "subdomains" : {
    "domains" : [ {
      "name" : "sub1.clone1.com",
      "id" : 3586214,
      "comment" : "sub1.clone1.com uses rackspace.com for email domain name. Sister subdomains are sub2.clone1.com, sub3.clone1.com",
      "updated" : "2013-05-06T17:17:36.000+0000",
      "emailAddress" : "administrator@rackspace.com",
      "created" : "2013-05-06T17:17:36.000+0000"
    }, {
      "name" : "sub2.clone1.com",
      "id" : 3586215,
      "comment" : "sub1.clone1.com uses parent domain name, clone1.com, for email domain name",
      "updated" : "2013-05-06T17:17:37.000+0000",
      "emailAddress" : "admin@clone1.com",
      "created" : "2013-05-06T17:17:37.000+0000"
    }, {
      "name" : "sub3.clone1.com",
      "id" : 3586216,
      "comment" : "sub3.clone1.com uses it's own domain name for email domain name",
      "updated" : "2013-05-06T17:17:37.000+0000",
      "emailAddress" : "adm@sub3.clone1.com",
      "created" : "2013-05-06T17:17:37.000+0000"
    } ],
    "totalEntries" : 3
  },
  "ttl" : 7788,
  "emailAddress" : "owner@clone1.com",
  "created" : "2013-05-06T17:17:31.000+0000"
}

Import domain#

POST /v1.0/{account}/domains/import

Imports a new domain with the configuration specified by the request.

Note

This call returns an asynchronous response, as described in Synchronous and asynchronous responses.

This call provisions a new DNS domain under the account specified by the BIND 9 formatted file configuration contents defined in the request object.  If the corresponding request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 (Bad Request) error response will be returned with information regarding the nature of the failure in the body of the response. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST the request again.

For all practical purposes, a successful Import domain call creates a domain, and is therefore similar in response to a Create domain call.

Note

This process allows multiple records to be created along with the domain. This is an atomic operation, so if there is a failure in the creation of even a single record, the entire process will fail.

Ensure that the BIND 9 formatted file configuration contents are valid by adhering to the following rules:

  • Each record starts on a new line and on the first column. If a record will not fit on one line, use the BIND_9 line continuation convention where you put a left parenthesis and continue the one record on the next line and put a right parenthesis when the record ends. For example,

  • The attribute values of a record must be separated by a single blank or tab. No other white space characters.

  • If there are any NS records, the data field should not be ns.rackspace.com or ns2.rackspace.com. They will result in “duplicate record” errors.

Not following the above rules strictly will result in an HTTP 400 (Bad Request) error response with messages such as the following: “The request could not be understood by the server due to malformed syntax.”

Note

  • If you attempt to import a domain that already exists, the API will return an exception saying that the domain already exists. This is the same behavior as when you attempt to create a domain that already exists.

  • The domain can have a comment attribute specified in the import domain request, and that comment is transferred to the new domain. However the domain contents cannot have comments specified in them. For example, no record level comments can be used in the import domain request.

  • The normal bind rules apply to any imported bind file, and in particular, records without a specified TTL will receive the domain TTL as the default. If the domain TTL is not specified, the SOA minTTL (3600 seconds) is used as the default instead.

Note

The following examples show the final successful response for the asynchronous call.

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Accepted

Request is accepted.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

400 500

dnsFault

The DNS service has experienced a fault.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

404

Not Found

The requested item was not found.

409

Already Exists

The item already exists.

413

Over Limit

The number of items returned is above the allowed limit.

503

Service Unavailable

The service is not available.

Request#

This table shows the header parameters for the request:

Name

Type

Description

X-Auth-Token

String

Arbitrary character string generated by the authentication service in response to valid credentials.

This table shows the URI parameters for the request:

Name

Type

Description

{account}

String

The tenant ID.

This table shows the body parameters for the request:

Name

Type

Description

domains[*].contentType

String

The content type for the bind file. Must be specified as “BIND_9”.

domains[*].contents

String

The valid configuration contents for the domain to be imported.

Example Import domain: XML request

POST https://dns.api.rackspacecloud.com/v1.0/1234/domains/import
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 543

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domains xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <domain contentType="BIND_9">
        <contents>
example.net. 3600 IN SOA ns.rackspace.com. sample@rackspace.com. 1308874739 3600 3600 3600 3600
example.net. 86400 IN A 110.11.12.16
example.net. 3600 IN MX 5 mail2.example.net.
www.example.net. 5400 IN CNAME example.net.
</contents>
    </domain>
</domains>

Example Import domain: JSON request

POST https://dns.api.rackspacecloud.com/v1.0/1234/domains/import
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 311

{
  "domains" : [ {
    "contentType" : "BIND_9",
    "contents" : "\nexample.net. 3600 IN SOA ns.rackspace.com. sample@rackspace.com. 1308874739 3600 3600 3600 3600\nexample.net. 86400 IN A 110.11.12.16\nexample.net. 3600 IN MX 5 mail2.example.net.\nwww.example.net. 5400 IN CNAME example.net.\n"
  } ]
}

Response#

Example Import domain: XML response

Status: 202 Accepted
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/xml
Content-Length: 855

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domains xmlns:ns2="http://www.w3.org/2005/Atom" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <domain name="example.net" ttl="3600" emailAddress="sample@rackspace.com" comment="Optional domain comment...">
        <nameservers>
            <nameserver name="ns.rackspace.com"/>
            <nameserver name="ns2.rackspace.com"/>
        </nameservers>
        <recordsList totalEntries="3">
            <record type="A" name="example.net" data="110.11.12.16" ttl="86400"/>
            <record type="MX" name="example.net" data="mail2.example.net" ttl="3600" priority="5"/>
            <record type="CNAME" name="www.example.net" data="example.net" ttl="5400"/>
        </recordsList>
    </domain>
</domains>

Example Import domain: JSON response

Status: 202 Accepted
Date: Thu, 28 Jul 2011 21:54:21 GMT
X-API-VERSION: 1.0.17
Content-Type: application/json
Content-Length: 756

{
  "domains" : [ {
    "name" : "example.net",
    "comment" : "Optional domain comment...",
    "nameservers" : [ {
      "name" : "ns.rackspace.com"
    }, {
      "name" : "ns2.rackspace.com"
    } ],
    "recordsList" : {
      "totalEntries" : 3,
      "records" : [ {
        "name" : "example.net",
        "type" : "A",
        "data" : "110.11.12.16",
        "ttl" : 86400
      }, {
        "name" : "example.net",
        "priority" : 5,
        "type" : "MX",
        "data" : "mail2.example.net",
        "ttl" : 3600
      }, {
        "name" : "www.example.net",
        "type" : "CNAME",
        "data" : "example.net",
        "ttl" : 5400
      } ]
    },
    "ttl" : 3600,
    "emailAddress" : "sample@rackspace.com"
  } ]
}