Chapter 7. Create 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, and/or response information of the call to be retrieved at a later point in time.

You need to use the Create Domain API call (/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

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

ttl=3600
emailAddress="sample@rackspace.com"
comment="Optional domain comment..."

With subdomains as follows:

Domain name = sub1.example.com

	Note
	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

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

	Note
	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 Chapter 9, Add Records instead.

The following examples show the cURL requests for Create Domain:

Example 7.1. cURL Create Domain Request: XML

curl -i -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: your_auth_token' \
-H 'Content-Type: application/xml' \
-H 'Accept: application/xml' \            
'https://dns.api.rackspacecloud.com/v1.0/your_acct_id/domains'

Example 7.2. cURL Create Domain Request: JSON

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

            } ]
        },
        "ttl" : 3600,
        "emailAddress" : "sample@rackspace.com"
} ]
}' \
-H 'X-Auth-Token: your_auth_token' \
-H 'Content-Type: application/json' \
'https://dns.api.rackspacecloud.com/v1.0/your_acct_id/domains'

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

your_name — use some variant of your name to ensure a unique domain name when it is used as a prefix for your domain name (your_name_example.com).
your_auth_token — as returned in your authentication response (see the response examples in Chapter 5, Generate an Authentication Token)
your_acct_id — as returned in your authentication response (must be replaced in the request URL)

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

Example 7.3. Create Domain Initial Asynchronous Response: XML

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> &lt;domains xmlns:ns2=&quot;http://docs.rackspacecloud.com/dns/api/management/v1.0&quot;
    xmlns=&quot;http://docs.rackspacecloud.com/dns/api/v1.0&quot; xmlns:ns3=&quot;http://www.w3.
    org/2005/Atom&quot;&gt;
    &lt;domain name=&quot;example.com&quot; ttl=&quot;3600&quot; emailAddress=&quot;sample@rackspace.com&quot;
    comment=&quot;Optional domain comment...&quot;&gt;
    &lt;subdomains&gt;
    &lt;domain name=&quot;sub1.example.com&quot; emailAddress=&quot;sample@rackspace.com&quot; comment=&quot;1st sample subdomain&quot;/&gt;
    &lt;domain name=&quot;sub2.example.com&quot; emailAddress=&quot;sample@rackspace.com&quot; comment=&quot;1st sample subdomain&quot;/&gt;
    &lt;/subdomains&gt;
    &lt;/domain&gt;
    &lt;/domains&gt;
    </request>
</asyncResponse>

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

Example 7.4. Create Domain Initial Asynchronous Response: JSON

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, and/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:

Example 7.5. cURL Asynchronous Status for Create Domain Request: XML

curl -i  \
-H 'X-Auth-Token: your_auth_token' \
-H 'Content-Type: application/xml' \
-H 'Accept: application/xml' \            
'https://dns.api.rackspacecloud.com/v1.0/your_acct_id/status/job_id?showDetails=true'

Example 7.6. cURL Asynchronous Status for Create Domain Request: JSON

curl -i  \
-H 'X-Auth-Token: your_auth_token' \
-H 'Content-Type: application/json' \
'https://dns.api.rackspacecloud.com/v1.0/your_acct_id/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:

your_auth_token — as returned in your authentication response (see the response examples in Chapter 5, Generate an Authentication Token)
your_acct_id — as returned in your authentication response (must be replaced in the request URL)
job_id — as returned in your Create Domain response (must be replaced in the request URL)

	Note
	The following examples show the final successful response for the asynchronous call. Refer to http://docs.rackspace.com/cdns/api/v1.0/cdns-devguide/content/sync_asynch_responses.html for more information about how the asynchronous call works.

The following examples show the final successful responses for Create Domain:

Example 7.7. Create Domain Final Successful Response: XML

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> &lt;domains xmlns:ns2=&quot;http://docs.rackspacecloud.com/dns/api/management/v1.0&quot;
    xmlns=&quot;http://docs.rackspacecloud.com/dns/api/v1.0&quot; xmlns:ns3=&quot;http://www.w3.
    org/2005/Atom&quot;&gt;
    &lt;domain name=&quot;example.com&quot; ttl=&quot;3600&quot; emailAddress=&quot;sample@rackspace.com&quot;
    comment=&quot;Optional domain comment...&quot;&gt;
    &lt;subdomains&gt;
    &lt;domain name=&quot;sub1.example.com&quot; emailAddress=&quot;sample@rackspace.com&quot; comment=&quot;1st sample subdomain&quot;/&gt;
    &lt;domain name=&quot;sub2.example.com&quot; emailAddress=&quot;sample@rackspace.com&quot; comment=&quot;1st sample subdomain&quot;/&gt;
    &lt;/subdomains&gt;
    &lt;/domain&gt;
    &lt;/domains&gt;
    </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="dns1.stabletransit.com"/>
                <nameserver name="dns2.stabletransit.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="dns1.stabletransit.com"/>
                        <nameserver name="dns2.stabletransit.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="dns1.stabletransit.com"/>
                        <nameserver name="dns2.stabletransit.com"/>
                    </nameservers>
                </domain>
            </subdomains>
        </domain>
    </response>
</asyncResponse>

Example 7.8. Create Domain Final Successful Response: JSON

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": "dns1.stabletransit.com"
              },
              {
                "name": "dns2.stabletransit.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": "dns1.stabletransit.com"
              },
              {
                "name": "dns2.stabletransit.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": "dns1.stabletransit.com"
        },
        {
          "name": "dns2.stabletransit.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.

	Note
	The response examples show the final successful response for the asynchronous call. Refer to http://docs.rackspace.com/cdns/api/v1.0/cdns-devguide/content/sync_asynch_responses.html for more information about how the asynchronous call works.

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.

Legal notices