Create and manage DNS domains#

You can use the examples in the following sections to create and manage domains by using Cloud DNS API operations.

You will perform the following tasks:

  • Creating two Cloud Servers

  • Creating a DNS domain

  • Listing domain details

  • Adding records to your domains

The DNS service is not a regionalized service. DNS is therefore responsible for appropriate replication, caching, and overall maintenance of DNS data across regional boundaries to other DNS servers. The followings are examples of service access endpoints for Cloud DNS.

  • https://dns.api.rackspacecloud.com/v1.0/1234/

  • https://lon.dns.api.rackspacecloud.com/v1.0/1234/

When making a Cloud DNS API call call, place the endpoint at the beginning of the request URL,for example: https://dns.api.rackspacecloud.com/v1.0/**your_acct_id**, as you can see in cURL request examples for this guide.

Note

These examples use the $API_ENDPOINT, $AUTH_TOKEN, and $TENANT_ID environment variables to specify the API endpoint, authentication token, and project ID values for accessing the service. Make sure you configure these variables before running the code samples.

Note

All examples in this guide assume that you are operating against the US region.

Creating a new cloud server#

This guide requires two cloud servers for setting up DNS using the Cloud DNS API. If you will be using two existing cloud servers on your account for this purpose, skip Steps 1-5 and go directly to Step 6 below. Otherwise, follow the steps below:

Create a cloud server using the cloud servers section of the Rackspace Public Cloud site.

Note

You can also create a cloud server using the Cloud Servers API. Refer to the Cloud Servers API basic operations for details.

To create a cloud server using the Cloud Control Panel:#

  1. Click Servers to view the Cloud Servers page.

  2. Click Create Server.

  3. Specify the Server Name and select a Size for your cloud server, then click Create Server.

  4. Using the Region drop-down menu, select the appropriate region.

  5. Select an image from a list of different operating systems, including Linux Distributions and Windows Images. For the purposes of this exercise, you can select any image listed and the two servers do not need to use the same image.

  6. Select the desired Flavor. 1 GB General Purpose v1 is suggested for this exercise.

  7. Click Create Server to create your server.

  8. Record the IP address listed for your cloud server below:

    • FIRST cloud server IP address = ___________________________________

    Also make a note of the root admin password, since you will need it to perform administrative tasks on the server.

  9. Repeat steps 2-8 to create a second cloud server.

  10. Record the IP address listed for your cloud server below:

    • SECOND cloud server IP address = ________________________________

    Also make a note of the root admin password, since you will need it to perform administrative tasks on the server.

Creating a domain#

The Create domain API 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.

This call returns an asynchronous response. In fact, PUT, POST, and DELETE DNS API calls are all asynchronous, since they may take some time to process. Therefore they return 202 ACCEPTED responses containing information with a callback URL, which allows the progress, status, or response information of the call to be retrieved at a later point in time.

You need to use the Create domain API call (POST /domains) to create a domain with the configuration that you specify.

In this case, assume that you want to create a domain with the following configuration:

  • Domain name=example.com

    • The DNS specification reserves “example.com” for documentation purposes. Therefore you will need to substitute your own domain name in order for the examples to work with the Cloud DNS API. To name your domain, you can use any letter, numbers between 0 and 9, and the character “-“. For example, you might use your first name and last initial at the beginning of the name, as follows: “bobmexample.com.”

  • ttl=3600

  • emailAddress=”sample@rackspace.com

  • comment=”Optional domain comment…”

  • With subdomains as follows:

    • Domain name = sub1.example.com

      • Remember to modify the domain name “sub1.example.com” listed above to conform to the name you have chosen for your domain, for example: “sub1.<your_domain_name>”.

    • emailAddress=”sample@rackspace.com

    • comment=”1st sample subdomain”

    • Domain name = sub2.example.com

      • Remember to modify the domain name “sub2.example.com” listed above to conform to the name you have chosen for your domain, for example: “sub2.<your_domain_name>”.

    • emailAddress=”sample@rackspace.com

    • comment=”2nd sample subdomain”

Although you could add records for your domain in this Create domain call, to keep things simple, you will add the records using the separate Add records call in Adding records instead.

The following examples show the cURL requests for Create domain:

cURL Create domain: request#

XML request

$ curl -s -d \
'<domains xmlns:ns2="http://docs.rackspacecloud.com/dns/api/management/v1.0"
xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://www.w3.
org/2005/Atom">
    <domain name="your_domain_name" ttl="3600" emailAddress="sample@rackspace.com"
comment="Optional domain comment...">
        <subdomains>
            <domain name="sub1.your_domain_name" emailAddress="sample@rackspace.
com" comment="1st sample subdomain"/>
            <domain name="sub2.your_domain_name" emailAddress="sample@rackspace.
com" comment="1st sample subdomain"/>
        </subdomains>
    </domain>
</domains>' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
"$API_ENDPOINT/domains" | ppxml

JSON request

$ curl -s -d \
'{
    "domains" : [ {
        "name" : "your_domain_name",
        "comment" : "Optional domain comment...",
        "subdomains" : {
            "domains" : [ {
                "name" : "sub1.your_domain_name",
                "comment" : "1st sample subdomain",
                "emailAddress" : "sample@rackspace.com"
            }, {
                "name" : "sub2.your_domain_name",
                "comment" : "1st sample subdomain",
                "emailAddress" : "sample@rackspace.com"

            } ]
        },
        "ttl" : 3600,
        "emailAddress" : "sample@rackspace.com"
} ]
}' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
"$API_ENDPOINT/domains" | python -m json.tool

Remember to replace the names in the examples above with their actual respective values for all the cURL examples that follow:

  • your_domain_name — to name your domain, you can use any letter, numbers between 0 and 9, and the character “-“.

The following examples show the initial asynchronous responses for Create domain:

Create domain: initial asynchronous response#

XML Response

HTTP/1.1 202 Accepted
X-API-VERSION: 1.0.13
Content-Type: application/xml
Date: Thu, 15 Mar 2012 16:21:49 GMT
Content-Length: 1309
Server: Jetty(7.3.1.v20110307)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<asyncResponse xmlns="http://docs.rackspacecloud.com/dns/api/v1.0"
    xmlns:ns2="http://www.w3.org/2005/Atom"
    xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <jobId>c1b06e08-d7bd-4708-982e-30da5e64ce28</jobId>
    <callbackUrl>https://dns.api.rackspacecloud.com/v1.0/1234/status/c1b06e08-d7bd-4708-982e-30da5e64ce28</callbackUrl>
    <status>RUNNING</status>
    <requestUrl>http://dns.api.rackspacecloud.com/v1.0/1234/domains</requestUrl>
    <verb>POST</verb>
    <request> <;domains xmlns:ns2=";http://docs.rackspacecloud.com/dns/api/management/v1.0";
    xmlns=";http://docs.rackspacecloud.com/dns/api/v1.0"; xmlns:ns3=";http://www.w3.
    org/2005/Atom";>;
    <;domain name=";example.com"; ttl=";3600"; emailAddress=";sample@rackspace.com";
    comment=";Optional domain comment...";>;
    <;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";/>;
    <;/subdomains>;
    <;/domain>;
    <;/domains>;
    </request>
</asyncResponse>

The <request> in the XML response comes back with the request you sent, with the HTML entities encoded (<, >, or ").

JSON Response

HTTP/1.1 202 Accepted
X-API-VERSION: 1.0.13
Content-Type: application/json
Date: Thu, 15 Mar 2012 18:08:15 GMT
Content-Length: 931
Server: Jetty(7.3.1.v20110307)

{
"callbackUrl": "https://dns.api.rackspacecloud.com/v1.0/1234/status/ec180c96-5488-4b29-8d25-ce3e2985afd4",
  "jobId": "ec180c96-5488-4b29-8d25-ce3e2985afd4",
  "request": "{\n    \"domains\" : [ {\n        \"name\" : \"example.com\",   \n        \"comment\" : \"Optional domain comment...\",   \n        \"subdomains\" : {\n            \"domains\" : [ {\n                \"name\" : \"sub1.example.com\",\n                \"comment\" : \"1st sample subdomain\",\n                \"emailAddress\" : \"sample@rackspace.com\"\n            }, {\n                \"name\" : \"sub2.example.com\",\n                \"comment\" : \"1st sample subdomain\",\n                \"emailAddress\" : \"sample@rackspace.com\"\n\n            } ]\n        },\n        \"ttl\" : 3600,\n        \"emailAddress\" : \"sample@rackspace.com\"\n} ]\n}",
  "requestUrl": "http://dns.api.rackspacecloud.com/v1.0/1234/domains",
  "status": "RUNNING",
  "verb": "POST"
}

Notice that you can see the 202 ACCEPTED responses containing information with a callback URL (callbackUrl), which allows the progress, status, or response information of the call to be retrieved at a later point in time. When a request is made to the callback URL provided and the job is still running, another 202 ACCEPTED response is returned with the same information as the previous one. If the request is successful, the status is COMPLETED.

The following examples show the requests to get the status for the job using the jobID and callbackUrl provided (which you can see in the previous example). Note that the job_id is automatically inserted for you at the end of the callbackUrl, so you can just copy the entire callbackUrl and place it within the single quotes at the end of the cURL command. Then follow it with the ?showDetails=true parameter.

The following examples show the cURL status requests for Create domain:

cURL Create domain asynchronous status: request#

XML Request

$ curl -i  \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
"$API_ENDPOINT/status/job_id?showDetails=true"

JSON Request

$ curl -i  \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
"$API_ENDPOINT/status/job_id?showDetails=true"

Adding the parameter ?showDetails=true at the end of the end of the URL after the job_id causes the response to display all details for the asynchronous request, including the results, if they are available. Omitting this parameter causes just basic details to be displayed (jobId, callbackUrl, and status attributes).

Remember to replace the names in the examples above with their actual respective values for all the cURL examples that follow:

  • job_id — as returned in your Create Domain response (must be replaced in the request URL)

The following examples show the final successful responses for the Create domain asynchronous call. You can find more information about how asynchronous calls work in the Synchronous and asynchronous responses.

Create domain: final successful response#

XML Response

HTTP/1.1 200 OK
X-API-VERSION: 1.0.13
Content-Type: application/xml
Date: Thu, 15 Mar 2012 17:56:10 GMT
Content-Length: 2400
Server: Jetty(7.3.1.v20110307)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<asyncResponse xmlns="http://docs.rackspacecloud.com/dns/api/v1.0"
    xmlns:ns2="http://www.w3.org/2005/Atom"
    xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
    <jobId>b32efdff-e217-4a97-9851-aac406811a38</jobId>
    <callbackUrl>https://dns.api.rackspacecloud.com/v1.0/1234/status/b32efdff-e217-4a97-9851-aac406811a38</callbackUrl>
    <status>COMPLETED</status>
    <requestUrl>http://dns.api.rackspacecloud.com/v1.0/1234/domains</requestUrl>
    <verb>POST</verb>
    <request> <;domains xmlns:ns2=";http://docs.rackspacecloud.com/dns/api/management/v1.0";
    xmlns=";http://docs.rackspacecloud.com/dns/api/v1.0"; xmlns:ns3=";http://www.w3.
    org/2005/Atom";>;
    <;domain name=";example.com"; ttl=";3600"; emailAddress=";sample@rackspace.com";
    comment=";Optional domain comment...";>;
    <;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";/>;
    <;/subdomains>;
    <;/domain>;
    <;/domains>;
    </request>
    <response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="domains">
        <domain id="3191305" accountId="1234" name="example.com" ttl="3600"
            emailAddress="sample@rackspace.com" updated="2012-03-15T17:53:05Z"
            created="2012-03-15T17:53:05Z" comment="Optional domain comment...">
            <nameservers>
                <nameserver name="ns.rackspace.com"/>
                <nameserver name="ns2.rackspace.com"/>
            </nameservers>
            <subdomains>
                <domain id="3191307" accountId="1234" name="sub1.example.com" ttl="3600"
                    emailAddress="sample@rackspace.com" updated="2012-03-15T17:53:05Z"
                    created="2012-03-15T17:53:05Z" comment="1st sample subdomain">
                    <nameservers>
                        <nameserver name="ns.rackspace.com"/>
                        <nameserver name="ns2.rackspace.com"/>
                    </nameservers>
                </domain>
                <domain id="3191308" accountId="1234" name="sub2.example.com" ttl="3600"
                    emailAddress="sample@rackspace.com" updated="2012-03-15T17:53:05Z"
                    created="2012-03-15T17:53:05Z" comment="1st sample subdomain">
                    <nameservers>
                        <nameserver name="ns.rackspace.com"/>
                        <nameserver name="ns2.rackspace.com"/>
                    </nameservers>
                </domain>
            </subdomains>
        </domain>
    </response>
</asyncResponse>

JSON Response

HTTP/1.1 200 OK
X-API-VERSION: 1.0.13
Content-Type: application/json
Date: Thu, 15 Mar 2012 18:46:01 GMT
Content-Length: 1892
Server: Jetty(7.3.1.v20110307)

{
"request": "{\n    \"domains\" : [ {\n        \"name\" : \"example.com\",\n        \"comment\" : \"Optional domain comment...\",\n        \"subdomains\" : {\n            \"domains\" : [
{\n                \"name\" : \"sub1.example.com\",\n                \"comment\" : \"1st sample subdomain\",\n                \"emailAddress\" : \"sample@rackspace.com\"\n            }, {
\n                \"name\" : \"sub2.example.com\",\n                \"comment\" : \"1st sample subdomain\",\n                \"emailAddress\" : \"sample@rackspace.com\"\n\n            } ]\n
},\n        \"ttl\" : 3600,\n        \"emailAddress\" : \"sample@rackspace.com\"\n} ]\n}",
"response": {
  "domains": [
    {
      "name": "example.com",
      "id": 3191338,
      "comment": "Optional domain comment...",
      "accountId": 1234,
      "subdomains": {
        "domains": [
          {
            "name": "sub1.example.com",
            "id": 3191339,
            "comment": "1st sample subdomain",
            "accountId": 1234,
            "updated": "2012-03-15T18:08:16.000+0000",
            "ttl": 3600,
            "emailAddress": "sample@rackspace.com",
            "nameservers": [
              {
                "name": "ns.rackspace.com"
              },
              {
                "name": "ns2.rackspace.com"
              }
            ],
            "created": "2012-03-15T18:08:16.000+0000"
          },
          {
            "name": "sub2.example.com",
            "id": 3191340,
            "comment": "1st sample subdomain",
            "accountId": 1234,
            "updated": "2012-03-15T18:08:16.000+0000",
            "ttl": 3600,
            "emailAddress": "sample@rackspace.com",
            "nameservers": [
              {
                "name": "ns.rackspace.com"
              },
              {
                "name": "ns2.rackspace.com"
              }
            ],
            "created": "2012-03-15T18:08:16.000+0000"
          }
        ]
      },
      "updated": "2012-03-15T18:08:15.000+0000",
      "ttl": 3600,
      "emailAddress": "sample@rackspace.com",
      "nameservers": [
        {
          "name": "ns.rackspace.com"
        },
        {
          "name": "ns2.rackspace.com"
        }
      ],
      "created": "2012-03-15T18:08:15.000+0000"
    }
  ]
},
"status": "COMPLETED",
"verb": "POST",
"jobId": "ec180c96-5488-4b29-8d25-ce3e2985afd4",
"callbackUrl": "https://dns.api.rackspacecloud.com/v1.0/1234/status/ec180c96-5488-4b29-8d25-ce3e2985afd4",
"requestUrl": "http://dns.api.rackspacecloud.com/v1.0/1234/domains"
}

Notice that you can see the 200 OK responses containing information about the domain/subdomains with status COMPLETED. This indicates that the call was successfully completed.

You can find more information about how asynchronous calls work in the Synchronous and asynchronous responses.

In the previous examples, you can see that the domain example.com was created along with its subdomains sub1.example.com and sub2.example.com. You will need the domain id for making the List domain details call in the next section, and you should supply this value wherever you see the field domain_id in the examples in this guide.

Listing domain details#

This operation provides detailed output for a specific domain configured and associated with your account. This operation is not capable of returning details for a domain that has been deleted.

This operation does not require a request body.

The examples list the details for the domain with domain_id that you created in the previous section.

The following examples show the cURL requests for List domain details:

cURL List domain details: request#

XML request

$ curl -s  \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Accept: application/xml"  \
"$API_ENDPOINT/domains/domain_id" | ppxml

JSON request

curl -s  \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Accept: application/json"  \
"$API_ENDPOINT/domains/domain_id" | python -m json.tool

Remember to replace the names in the examples above with their actual respective values for all the cURL examples that follow:

  • domain_id — as returned in your create domain response (must be replaced in the request URL)

The following examples show the List domain details responses:

List domain details: response#

XML response

HTTP/1.1 200 OK
X-API-VERSION: 1.0.13
Content-Type: application/xml
Date: Thu, 15 Mar 2012 19:51:54 GMT
Content-Length: 903
Server: Jetty(7.3.1.v20110307)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns2="http://www.w3.org/2005/Atom"
  xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0" id="3191338" accountId="1234"
  name="example.com" ttl="3600" emailAddress="sample@rackspace.com" updated="2012-03-15T18:08:15Z"
  created="2012-03-15T18:08:15Z" comment="Optional domain comment...">
  <nameservers>
    <nameserver name="ns.rackspace.com"/>
    <nameserver name="ns2.rackspace.com"/>
  </nameservers>
  <recordsList totalEntries="2">
    <record id="NS-7475194" type="NS" name="example.com" data="ns.rackspace.com" ttl="3600" updated="2012-03-15T18:08:15Z" created="2012-03-15T18:08:15Z"/>
    <record id="NS-7475195" type="NS" name="example.com" data="ns2.rackspace.com" ttl="3600" updated="2012-03-15T18:08:15Z" created="2012-03-15T18:08:15Z"/>
  </recordsList>
</domain>

JSON response

HTTP/1.1 200 OK
X-API-VERSION: 1.0.13
Content-Type: application/json
Date: Thu, 15 Mar 2012 19: 54: 52 GMT
Content-Length: 713
Server: Jetty(7.3.1.v20110307)


{
  "name": "example.com",
  "id": 3191338,
  "comment": "Optional domain comment...",
  "accountId": 1234,
  "updated": "2012-03-15T18:08:15.000+0000",
  "ttl": 3600,
  "recordsList": {
    "records": [
      {
        "name": "example.com",
        "id": "NS-7475194",
        "type": "NS",
        "data": "ns.rackspace.com",
        "updated": "2012-03-15T18:08:15.000+0000",
        "ttl": 3600,
        "created": "2012-03-15T18:08:15.000+0000"
      },
      {
        "name": "example.com",
        "id": "NS-7475195",
        "type": "NS",
        "data": "ns2.rackspace.com",
        "updated": "2012-03-15T18:08:15.000+0000",
        "ttl": 3600,
        "created": "2012-03-15T18:08:15.000+0000"
      }
    ],
    "totalEntries": 2
  },
  "emailAddress": "sample@rackspace.com",
  "nameservers": [
    {
      "name": "ns.rackspace.com"
    },
    {
      "name": "ns2.rackspace.com"
    }
  ],
  "created": "2012-03-15T18:08:15.000+0000"
}

By default, the List domain details API call lists details of the specified domain, with record information but without subdomains.

The following parameters are available to control the information displayed by the List domain details responses:

  • showRecords — if this parameter is set to true, then information about 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.

For example, using the following version of the call, information about subdomains will be displayed, but information about records will not be displayed: 'https://dns.api.rackspacecloud.com/v1.0/ your_acct_id /domains/ domain_id ?showRecords=false&showSubdomains=true

Displaying only the information needed will improve the performance of the List domain details call.

The following examples show the cURL requests for List domain details with subdomains but don’t show records:

cURL List domain details with subdomains, no records: request#

XML request

$ curl -i  \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Accept: application/xml"  \
"$API_ENDPOINT/domains/domain_id?showRecords=false&showSubdomains=true"

JSON request

$ curl -i  \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Accept: application/json"  \
"$API_ENDPOINT/domains/domain_id?showRecords=false&showSubdomains=true"

Remember to replace the names in the examples above with their actual respective values for all the cURL examples that follow:

  • domain_id — as returned in your create domain final successful response (see the examples in Creating a domain), this must be replaced in the request URL.

The following examples show the List domain details with subdomains, no records responses:

List domain details with subdomains, no records: response#

XML response

HTTP/1.1 200 OK
X-API-VERSION: 1.0.13
Content-Type: application/xml
Date: Thu, 15 Mar 2012 21:16:28 GMT
Content-Length: 865
Server: Jetty(7.3.1.v20110307)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<domain xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns2="http://www.w3.org/2005/Atom"
  xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0" id="3191338" accountId="1234"
  name="example.com" ttl="3600" emailAddress="sample@rackspace.com" updated="2012-03-15T18:08:15Z"
  created="2012-03-15T18:08:15Z" comment="Optional domain comment...">
  <nameservers>
    <nameserver name="ns.rackspace.com"/>
    <nameserver name="ns2.rackspace.com"/>
  </nameservers>
  <subdomains totalEntries="2">
    <domain id="3191339" name="sub1.example.com" updated="2012-03-15T18:08:16Z" created="2012-03-15T18:08:16Z" comment="1st sample subdomain"/>
    <domain id="3191340" name="sub2.example.com" updated="2012-03-15T18:08:17Z" created="2012-03-15T18:08:16Z" comment="1st sample subdomain"/>
  </subdomains>
</domain>

JSON response

HTTP/1.1 200 OK
X-API-VERSION: 1.0.13
Content-Type: application/json
Date: Thu, 15 Mar 2012 19: 54: 52 GMT
Content-Length: 713
Server: Jetty(7.3.1.v20110307)

{
   "id": "3191338",
   "accountId": "1234",
   "name": "example.com",
   "ttl": "3600",
   "emailAddress": "sample@rackspace.com",
   "updated": "2012-03-15T18:08:15Z",
   "created": "2012-03-15T18:08:15Z",
   "comment": "Optional domain comment...",
   "nameservers": {
      "nameserver": [
         {
            "name": "ns.rackspace.com"
         },
         {
            "name": "ns2.rackspace.com"
         }
      ]
   },
   "subdomains": {
      "totalEntries": "2",
      "domain": [
         {
            "id": "3191339",
            "name": "sub1.example.com",
            "updated": "2012-03-15T18:08:16Z",
            "created": "2012-03-15T18:08:16Z",
            "comment": "1st sample subdomain"
         },
         {
            "id": "3191340",
            "name": "sub2.example.com",
            "updated": "2012-03-15T18:08:17Z",
            "created": "2012-03-15T18:08:16Z",
            "comment": "1st sample subdomain"
         }
      ]
   }
}

Adding records#

This section shows you how to add records for your new domain:

  • Two A records to map the IPV4 addresses of your two cloud servers that you recorded in Create a new cloud server. to the new domain that you created in Create a domain.

  • One CNAME record to create an alias (www.example.com) for your domain with a TTL of 5400 and a comment of “This is a comment on the CNAME record.”

  • Make the first cloud server the ftp server (ftp.example.com) for your domain with a TTL of 5571.

  • Make the second cloud server the domain server with a TTL of 86400.

Note

If you had IPV6 addresses to map, you would need to create AAAA records in addition to any A records for IPv4 addresses.

The following examples show the cURL requests for Add records:

cURL Add records: request#

XML Request

$ curl -s -d \
'<?xml version="1.0" ?>
<recordsList xmlns:ns2="http://docs.rackspacecloud.com/dns/api/management/v1.
0" xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns3="http://www.
w3.org/2005/Atom">
    <record type="A" name="ftp.example.com"
    data="your_FIRST_Cloud_Server_IP_address" ttl="5771"/>
    <record type="A" name="example.com"
    data="your_SECOND_Cloud_Server_IP_address" ttl="86400"/>
    <record type="CNAME" name="www.example.com" data="example.com" ttl="5400"
    comment="This is a comment on the CNAME record"/>
</recordsList>' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
"$API_ENDPOINT/domains/domain_id/records" | ppxml

JSON request

$ curl -s -d \
'{
    "records": [
        {
            "name" : "ftp.example.com",
            "type" : "A",
            "data" : "your_FIRST_Cloud_Server_IP_address",
            "ttl" : 5771
        },
        {
            "name" : "example.com",
            "type" : "A",
            "data" : "your_SECOND_Cloud_Server_IP_address",
            "ttl" : 86400
        },
        {
            "name" : "www.example.com",
            "type" : "CNAME",
            "comment" : "This is a comment on the CNAME record",
            "data" : "example.com",
            "ttl" : 5400
        }
    ]
}' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
"$API_ENDPOINT/domains/domain_id/records" | python -m json.tool

Remember to replace the names in the examples above with their actual respective values:

  • domain_id — as returned in your create domain final successful response (see the examples in Creating a domain), this must be replaced in the request URL.

The following examples show the initial asynchronous responses for Add records:

Initial asynchronous response#

XML Response

HTTP/1.1 202 Accepted
X-API-VERSION: 1.0.13
Content-Type: application/xml
Date: Fri, 16 Mar 2012 15:17:52 GMT
Content-Length: 1283
Server: Jetty(7.3.1.v20110307)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<asyncResponse xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns2="http://www.w3.org/2005/Atom" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
  <jobId>1912f480-4636-498e-bba4-609661d19083</jobId>
  <callbackUrl>https://dns.api.rackspacecloud.com/v1.0/1234/status/1912f480-4636-498e-bba4-609661d19083</callbackUrl>
  <status>RUNNING</status>
  <requestUrl>http://dns.api.rackspacecloud.com/v1.0/1234/domains/3191338/records</requestUrl>
  <verb>POST</verb>
  <request><;?xml version=";1.0"; ?>;
<;recordsList xmlns:ns2=";http://docs.rackspacecloud.com/dns/api/management/v1.
0"; xmlns=";http://docs.rackspacecloud.com/dns/api/v1.0"; xmlns:ns3=";http://www.
w3.org/2005/Atom";>;
<;record type=";A"; name=";ftp.example.com";
  data=";50.56.207.146"; ttl=";5771";/>;
<;record type=";A"; name=";example.com";
  data=";108.166.67.215"; ttl=";86400";/>;
<;record type=";CNAME"; name=";www.example.com"; data=";example.com"; ttl=";5400";
  comment=";This is a comment on the CNAME record";/>;
<;/recordsList>;</request>
</asyncResponse>

JSON response

HTTP/1.1 202 Accepted
X-API-VERSION: 1.0.13
Content-Type: application/json
Date: Fri, 16 Mar 2012 17:16:16 GMT
Content-Length: 700
Server: Jetty(7.3.1.v20110307)

{
  "request": "{\n\"records\": [\n{\n\"name\" : \"ftp.example.com\",\n\"type\" : \"A\",\n\"data\" : \"50.56.207.146\",\n\"ttl\" : 5771\n},\n{\n\"name\" : \"example.com\",\n\"type\" : \"A\",\n\"data\" : \"108.166.67.215\",\n\"ttl\" : 86400\n},\n{\n\"name\" : \"www.example.com\",\n\"type\" : \"CNAME\",\n\"comment\" : \"This is a comment on the CNAME record\",\n\"data\" : \"example.com\",\n\"ttl\" : 5400\n}\n]\n}",
  "status": "RUNNING",
  "verb": "POST",
  "jobId": "e6b78833-2b5e-4c4c-88c6-6aabb55a706b",
  "callbackUrl": "https://dns.api.rackspacecloud.com/v1.0/1234/status/e6b78833-2b5e-4c4c-88c6-6aabb55a706b",
  "requestUrl": "http://dns.api.rackspacecloud.com/v1.0/1234/domains/3191338/records"
}

The following examples show the cURL asynchronous status requests for Add records:

cURL asynchronous status for Add records: request#

XML request

$ curl -i  \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
"$API_ENDPOINT/status/job_id?showDetails=true"

JSON request

$ curl -i  \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Project-Id: $TENANT_ID" \
-H "Content-Type: application/json" \
"$API_ENDPOINT/status/job_id?showDetails=true"

Adding the parameter ?showDetails=true at the end of the end of the URL after the job_id causes the response to display all details for the aynch request, including the results, if they are available. Omitting this parameter causes just basic details to be displayed (jobId, callbackUrl, and status attributes).

Remember to replace the names in the examples above with their actual respective values for all the cURL examples that follow:

  • job_id — as returned in your Create domain response (must be replaced in the request URL)

The following examples show the final successful response for the asynchronous Add records call. Refer to Synchronous and asynchronous responses for more information about how the asynchronous call works.

cURL Add records: final successful response#

XML response

HTTP/1.1 200 OK
X-API-VERSION: 1.0.13
Content-Type: application/xml
Date: Fri, 16 Mar 2012 15:53:22 GMT
Content-Length: 1906
Server: Jetty(7.3.1.v20110307)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<asyncResponse xmlns="http://docs.rackspacecloud.com/dns/api/v1.0" xmlns:ns2="http://www.w3.org/2005/Atom" xmlns:ns3="http://docs.rackspacecloud.com/dns/api/management/v1.0">
  <jobId>1912f480-4636-498e-bba4-609661d19083</jobId>
  <callbackUrl>https://dns.api.rackspacecloud.com/v1.0/1234/status/1912f480-4636-498e-bba4-609661d19083</callbackUrl>
  <status>COMPLETED</status>
  <requestUrl>http://dns.api.rackspacecloud.com/v1.0/1234/domains/3191338/records</requestUrl>
  <verb>POST</verb>
  <request><;?xml version=";1.0"; ?>;
<;recordsList xmlns:ns2=";http://docs.rackspacecloud.com/dns/api/management/v1.
0"; xmlns=";http://docs.rackspacecloud.com/dns/api/v1.0"; xmlns:ns3=";http://www.
w3.org/2005/Atom";>;
<;record type=";A"; name=";ftp.example.com";
  data=";50.56.207.146"; ttl=";5771";/>;
<;record type=";A"; name=";example.com";
  data=";108.166.67.215"; ttl=";86400";/>;
<;record type=";CNAME"; name=";www.example.com"; data=";example.com"; ttl=";5400";
  comment=";This is a comment on the CNAME record";/>;
<;/recordsList>;</request>
  <response xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="recordsList">
    <record id="A-8135987" type="A" name="ftp.example.com" data="50.56.207.146" ttl="5771" updated="2012-03-16T15:17:53Z" created="2012-03-16T15:17:53Z"/>
    <record id="A-8135988" type="A" name="example.com" data="108.166.67.215" ttl="86400" updated="2012-03-16T15:17:53Z" created="2012-03-16T15:17:53Z"/>
    <record id="CNAME-10713155" type="CNAME" name="www.example.com" data="example.com" ttl="5400" updated="2012-03-16T15:17:54Z" created="2012-03-16T15:17:54Z" comment="This is a comment on the CNAME record"/>
  </response>
</asyncResponse>

JSON response

HTTP/1.1 200 OK
X-API-VERSION: 1.0.13
Content-Type: application/json
Date: Fri, 16 Mar 2012 16:16:23 GMT
Content-Length: 1455
Server: Jetty(7.3.1.v20110307)

{
"request": "{\n\"records\": [\n{\n\"name\" : \"ftp.example.com\",\n\"type\" : \"A\",\n\"data\" : \"50.56.207.146\",\n\"ttl\" : 5771\n},\n{\n\"name\" : \"example.com\",\n\"type\" : \"A\",\n\"data\" : \"108.166.67.215\",\n\"ttl\" : 86400\n},\n{\n\"name\" : \"www.example.com\",\n\"type\" : \"CNAME\",\n\"comment\" : \"This is a comment on the CNAME record\",\n\"data\" : \"example.com\",\n\"ttl\" : 5400\n}\n]\n}",
  "response": {
    "records": [
      {
        "name": "ftp.example.com",
        "id": "A-8135987",
        "type": "A",
        "data": "50.56.207.146",
        "updated": "2012-03-16T15:17:53.000+0000",
        "ttl": 5771,
        "created": "2012-03-16T15:17:53.000+0000"
      },
      {
        "name": "example.com",
        "id": "A-8135988",
        "type": "A",
        "data": "108.166.67.215",
        "updated": "2012-03-16T15:17:53.000+0000",
        "ttl": 86400,
        "created": "2012-03-16T15:17:53.000+0000"
      },
      {
        "name": "www.example.com",
        "id": "CNAME-10713155",
        "type": "CNAME",
        "comment": "This is a comment on the CNAME record",
        "data": "example.com",
        "updated": "2012-03-16T15:17:54.000+0000",
        "ttl": 5400,
        "created": "2012-03-16T15:17:54.000+0000"
      }
    ]
  },
  "status": "COMPLETED",
  "verb": "POST",
  "jobId": "1912f480-4636-498e-bba4-609661d19083",
  "callbackUrl": "https://dns.api.rackspacecloud.com/v1.0/1234/status/1912f480-4636-498e-bba4-609661d19083",
  "requestUrl": "http://dns.api.rackspacecloud.com/v1.0/1234/domains/3191338/records"
}

You can now call List domain details again to confirm that the records are added to your domain. See Listing domain details for instructions.