• Buy Now
    • Rackspace Cloud
    • Email & Apps
    • Fanatical Support for AWS
    • Managed Google Cloud Platform
    • Office 365
  • Log In
    • MyRackspace Portal
    • Cloud Control Panel
    • Rackspace Webmail Login
    • Cloud Office Control Panel
  • Rackspace Logo
  • Developer Home
  • Developer Documentation
  • Blogs ▼
    • Technical Blog
    • Rackspace Blog
    • Solve: Thought Leadership
  • Support Documentation

Developer Docs


Let’s Build Something Powerful Together!

End-to-End Multicloud Solutions.   Solving Together.™   Learn more at Rackspace.com

Submit an issue
  • Cloud DNS 1.0
  • Getting started
    • Get your credentials
    • Sending API requests to Cloud DNS
      • Convert cURL examples to run on Windows
    • Authenticate to the Rackspace Cloud
      • Authenticate by using cURL
      • Send an authentication request
      • Review the authentication response
      • Configure environment variables
    • Concepts
      • DNS
      • Domain
      • Subdomain
      • Record
      • Domain Owner
    • Create and manage DNS domains
      • Creating a new cloud server
      • Creating a domain
      • Listing domain details
      • Adding records
  • General API Information
    • Service access endpoints
    • DNS Service versions
      • Contract version
      • API version headers
    • Request and response types
    • Supported Record Types
      • Notes
      • Notes
    • Synchronous and asynchronous responses
      • Viewing status of all asynchronous job requests
    • IP Address Support
    • DNS propagation
    • Persistent Connections
    • Content Compression
    • Paginated collections
      • Pagination elements and attributes
    • Limits
      • Rate limits
      • Absolute limits
      • Retrieve account limits
    • Faults
    • Date and time format
    • Comments
    • Role-based access control (RBAC)
      • Assigning Roles to Account Users
      • Roles available for Rackspace Cloud DNS
      • Multiproduct global roles and permissions
      • Resolving conflicts between RBAC multiproduct and product-specific roles
      • RBAC permissions cross-reference to Rackspace Cloud DNS API operations
  • API reference
    • Limits operations
      • List limits
      • Show limits
      • List limit types
    • Domains operations
      • List domains
      • List domains by name
      • Create domain
      • Update domains
      • Delete domains
      • Delete domains and subdomains
      • Search domains
      • List domain details without subdomains
      • Show domain
      • Update domain
      • Delete domain
      • Delete domain and its subdomains
      • Show domain changes
      • Export domain
      • Clone domain
      • Import domain
    • Subdomains operations
      • List subdomains
    • Records operations
      • List records
      • Search records
      • Add records
      • Delete records
      • Update records
      • Delete record
      • Update record
      • Show record details
    • Reverse DNS operations
      • Update PTR records
      • Add PTR records
      • List PTR records
      • Delete PTR records
      • Show PTR record
  • Release notes
    • v1.0.34 Configuration Changes, October 24, 2014
      • What's new
      • Resolved issues
      • Known issues
    • v1.0.34, October 14, 2014
      • What's new
      • Resolved issues
      • Known issues
    • v1.0.33, July 29, 2014
      • What's new
      • Resolved issues
      • Known issues
    • v1.0.31 configuration changes, July 16, 2014
      • What's new
      • Resolved issues
      • Known issues
    • v1.0.31, June 26, 2014
      • What's new
      • Resolved issues
      • Known issues
  • Service updates
  • Additional resources
  • Disclaimer

Synchronous and asynchronous responses#

All successful GET requests are synchronous calls, since they are always retrieving (reading) existing information. With these requests, the caller waits until the call returns with the specified code and response body.

PUT, POST, and DELETE* calls are asynchronous, however, 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.

When the status of a request is queried (via a callbackUrl supplied by the API), only basic information regarding the status of the job is returned by default. If more detail is desired, any status URL may include an optional showDetails query parameter that will display more information regarding the original request:

GET /status/jobId ? showDetails = [true|false]

  • List status of the specified asynchronous request. Display details, as specified by the showDetails parameter.
  • Representations: XML, JSON

Normal Response Code(s): 200

Error Response Code(s): dnsFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), itemNotFound (404), overLimit (413)

The results of asynchronous calls are retained for up to 24 hours.

If a request body does not pass initial validation or an error condition arises, you may receive an immediate error response from the request.

The following list shows the complete set of attributes for asynchronous responses:

Table. Attributes for asynchronous responses

Attribute Description Inclusion
jobid An identifier for the specific request. Basic and Detail
callbackUrl Resource locator for querying the status of the request. Basic and Detail
status

An indicator of the request status: INITIALIZED, RUNNING, COMPLETED, or ERROR.

Note: INITIALIZED is the status that immediately precedes RUNNING and is the first possible status of a job. It indicates acceptance of the job.

Basic and Detail
requestUrl The URL of the original request. Detail only
verb The type of the original request: PUT, POST, or DELETE. Detail only
request The original request data, if any. Detail only
response The results of a COMPLETE operation, if any. Detail only
error The results of an ERROR operation. Detail only

The asynchronous response body will look similar to the following examples, depending on whether basic or detailed information is requested.

If you use the callback URL without specifying the query parameter showDetails=true, only basic information is returned (jobId, callbackUrl, and status attributes):

Example: Basic success asynchronous request: XML

GET https://dns.api.rackspacecloud.com/v1.0/1234/status/3593a5e9-83af-4eb8-ae1a-25f07b747d80
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example: Basic success asynchronous request: JSON

GET https://dns.api.rackspacecloud.com/v1.0/1234/status/3593a5e9-83af-4eb8-ae1a-25f07b747d80
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

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:

Example: Basic success asynchronous response: 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: 455

<?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>3593a5e9-83af-4eb8-ae1a-25f07b747d80</jobId>
    <callbackUrl>https://dns.api.rackspacecloud.com/v1.0/1234/status/3593a5e9-83af-4eb8-ae1a-25f07b747d80</callbackUrl>
    <status>COMPLETED</status>
</asyncresponse>

Example: Basic success asynchronous response: 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: 190

{
  "status" : "COMPLETED",
  "jobId" : "3593a5e9-83af-4eb8-ae1a-25f07b747d80",
  "callbackUrl" : "https://dns.api.rackspacecloud.com/v1.0/1234/status/3593a5e9-83af-4eb8-ae1a-25f07b747d80"
}

If you specify the query parameter showDetails=true for the callback URL, detailed information is returned (all attributes) :

Example: Detail success asynchronous request: XML

GET https://dns.api.rackspacecloud.com/v1.0/1234/status/3593a5e9-83af-4eb8-ae1a-25f07b747d80?showDetails=true
Accept: application/xml
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/xml
Content-Length: 0

Example: Detail success asynchronous request: JSON

GET https://dns.api.rackspacecloud.com/v1.0/1234/status/3593a5e9-83af-4eb8-ae1a-25f07b747d80?showDetails=true
Accept: application/json
X-Auth-Token: ea85e6ac-baff-4a6c-bf43-848020ea3812
Content-Type: application/json
Content-Length: 0

If the request is successful, this includes the response, which contains the results of the operation:

Example: Detail success asynchronous response: 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: 1187

<?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>3593a5e9-83af-4eb8-ae1a-25f07b747d80</jobId>
    <callbackUrl>https://dns.api.rackspacecloud.com/v1.0/1234/status/3593a5e9-83af-4eb8-ae1a-25f07b747d80</callbackUrl>
    <status>COMPLETED</status>
    <requestUrl>https://dns.api.rackspacecloud.com/v1.0/1234/domains</requestUrl>
    <verb>POST</verb>
    <request>{
        "domains" : [ {
        "name" : "example.com",
        "emailAddress" : "admin@example.com"
        } ]
        }
    </request>
    <response xsi:type="domains" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
        <domain id="12345" accountId="1234" name="example.com" ttl="3600" emailAddress="admin@example.com" updated="2011-08-23T14:02:54-05:00" created="2011-08-23T14:02:54-05:00">
            <nameservers>
                <nameserver name="ns.rackspace.com"/>
                <nameserver name="ns2.rackspace.com"/>
            </nameservers>
        </domain>
    </response>
</asyncresponse>

Example: Detail success asynchronous response: 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: 866

{
  "status" : "COMPLETED",
  "request" : "{\n        \"domains\" : [ {\n        \"name\" : \"example.com\",\n        \"emailAddress\" : \"admin@example.com\"\n        } ]\n        }\n    ",
  "verb" : "POST",
  "jobId" : "3593a5e9-83af-4eb8-ae1a-25f07b747d80",
  "callbackUrl" : "https://dns.api.rackspacecloud.com/v1.0/1234/status/3593a5e9-83af-4eb8-ae1a-25f07b747d80",
  "requestUrl" : "https://dns.api.rackspacecloud.com/v1.0/1234/domains",
  "response" : {
    "domains" : [ {
      "name" : "example.com",
      "id" : 12345,
      "updated" : "2011-08-23T19:02:54.000+0000",
      "nameservers" : [ {
        "name" : "ns.rackspace.com"
      }, {
        "name" : "ns2.rackspace.com"
      } ],
      "accountId" : 1234,
      "ttl" : 3600,
      "emailAddress" : "admin@example.com",
      "created" : "2011-08-23T19:02:54.000+0000"
    } ]
  }
}

Note

Examples of successful responses in the rest of this guide only demonstrate the contents of the asynchronous response attribute. Additional attributes and elements have been omitted for clarity.

If an error occurs as a result of processing the original request, querying the callback URL will return the information about the error. If you use the callback URL without specifying the query parameter showDetails=true, only basic information is provided:

Example: Basic error asynchronous response: 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: 451

<?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>e63886c9-acf0-4e5d-8023-09a0fae37446</jobId>
    <callbackUrl>https://dns.api.rackspacecloud.com/v1.0/1234/status/e63886c9-acf0-4e5d-8023-09a0fae37446</callbackUrl>
    <status>ERROR</status>
</asyncresponse>

Example: Basic error asynchronous response: 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: 186

{
  "status" : "ERROR",
  "jobId" : "e63886c9-acf0-4e5d-8023-09a0fae37446",
  "callbackUrl" : "https://dns.api.rackspacecloud.com/v1.0/1234/status/e63886c9-acf0-4e5d-8023-09a0fae37446"
}

If you use the callback URL with the query parameter showDetails=true, then detailed information is provided:

Example: Detail error asynchronous response: 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: 847

<?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>e63886c9-acf0-4e5d-8023-09a0fae37446</jobId>
    <callbackUrl>https://dns.api.rackspacecloud.com/v1.0/1234/status/e63886c9-acf0-4e5d-8023-09a0fae37446</callbackUrl>
    <status>ERROR</status>
    <requestUrl>https://dns.api.rackspacecloud.com/v1.0/1234/domains</requestUrl>
    <verb>POST</verb>
    <request>{
        "domains" : [ {
        "name" : "example.com",
        "emailAddress" : "admin@example.com"
        } ]
        }
    </request>
    <error code="409">
        <message>The object already exists.</message>
        <details>Domain already exists</details>
    </error>
</asyncresponse>

Example: Detail error asynchronous response: 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: 564

{
  "status" : "ERROR",
  "error" : {
    "message" : "The object already exists.",
    "code" : 409,
    "details" : "Domain already exists"
  },
  "request" : "{\n        \"domains\" : [ {\n        \"name\" : \"example.com\",\n        \"emailAddress\" : \"admin@example.com\"\n        } ]\n        }\n    ",
  "verb" : "POST",
  "jobId" : "e63886c9-acf0-4e5d-8023-09a0fae37446",
  "callbackUrl" : "https://dns.api.rackspacecloud.com/v1.0/1234/status/e63886c9-acf0-4e5d-8023-09a0fae37446",
  "requestUrl" : "https://dns.api.rackspacecloud.com/v1.0/1234/domains"
}

Note

Examples of error responses in the rest of this guide only show the contents of the asynchronous error attribute. Additional attributes and elements have been omitted for clarity.

Viewing status of all asynchronous job requests#

As well as viewing status for a particular job ID, as described in the previous section, you can also view status information for all asynchronous job requests for an account. You can also filter the information requested by using the following optional boolean request parameters:

  • showErrors – if true, specifies that errors are shown
  • showRunning – if true, specifies that jobs still running are shown
  • showCompleted – if true, specifies that completed jobs are shown
  • showDetails– if true, specifies that job details are shown

In addition, paging request parameters limit and offset can also be supplied for the request. See Pagination for details.

The default values for these request parameters (if they are not specified) are:

  • showErrors=true
  • showRunning=true
  • showCompleted=true
  • showDetails=false
  • limit=100
  • offset=0
Verb URI Description Representations
GET /status?showDetails=[true|false] &showErrors=[true|false] &showRunning=[true|false] &showCompleted=[true|false] &limit=int1 &offset=int2 List status of all asynchronous job requests for an account and filter the information requested by using the optional boolean request parameters. XML, JSON

List status of all asynchronous job requests for an account and filter the information requested by using the optional boolean request parameters.

Representations: XML, JSON

Normal Response Code(s): 200

Error Response Code(s): dnsFault (400, 500), serviceUnavailable (503), unauthorized (401), badRequest (400), itemNotFound (404), overLimit (413)

By omitting the showDetails parameter from the request (or explicitly setting it to false), you can request basic information for all errors, running jobs, and completed jobs for the account. By default (with no query parameters specified) only basic information is requested:

Example: Get basic status for all jobs request: XML

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

Example: Get basic status for all jobs request: JSON

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

The response lists all the user's jobs that have had errors, followed by those still running, and then those that have completed:

Example: Get basic status for all jobs response: XML

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<asyncjobsstatus totalEntries="12" 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">
    <asyncResponse>
        <jobId>1ada58ab-f413-4d7e-a139-19c96eaea8b2</jobId>
        <callbackUrl>http://dns.api.rackspacecloud.com/v1.0/1234/status/1ada58ab-f413-4d7e-a139-19c96eaea8b2?showDetails=true</callbackUrl>
        <status>COMPLETED</status>
    </asyncResponse>
    <asyncResponse>
        <jobId>34c0160a-6109-4b61-9ea4-1f0513df031b</jobId>
        <callbackUrl>http://dns.api.rackspacecloud.com/v1.0/1234/status/34c0160a-6109-4b61-9ea4-1f0513df031b?showDetails=true</callbackUrl>
        <status>COMPLETED</status>
    </asyncResponse>
</asyncjobsstatus>

Example: Get basic status for all jobs response: JSON

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

{
  "totalEntries" : 12,
  "asyncResponses" : [ {
    "status" : "COMPLETED",
    "jobId" : "1ada58ab-f413-4d7e-a139-19c96eaea8b2",
    "callbackUrl" : "http://dns.api.rackspacecloud.com/v1.0/1234/status/1ada58ab-f413-4d7e-a139-19c96eaea8b2?showDetails=true"
  }, {
    "status" : "COMPLETED",
    "jobId" : "34c0160a-6109-4b61-9ea4-1f0513df031b",
    "callbackUrl" : "http://dns.api.rackspacecloud.com/v1.0/1234/status/34c0160a-6109-4b61-9ea4-1f0513df031b?showDetails=true"
  } ]
}

To get detailed status information for all jobs, set the showDetails parameter to true (showDetails=true):

Example: Get detailed status for all jobs request: XML

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

Example: Get detailed status for all jobs request: JSON

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

The response lists all the user's jobs that have had errors, followed by those still running, and then those that have completed:

Example: Get detailed status for all jobs response: XML

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<asyncjobsstatus totalEntries="12" 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">
    <asyncResponse>
        <jobId>1ada58ab-f413-4d7e-a139-19c96eaea8b2</jobId>
        <callbackUrl>http://dns.api.rackspacecloud.com/v1.0/1234/status/1ada58ab-f413-4d7e-a139-19c96eaea8b2?showDetails=true</callbackUrl>
        <status>COMPLETED</status>
        <requestUrl>http://dns.api.rackspacecloud.com/v1.0/1234/domains/2764176</requestUrl>
        <verb>DELETE</verb>
    </asyncResponse>
    <asyncResponse>
        <jobId>34c0160a-6109-4b61-9ea4-1f0513df031b</jobId>
        <callbackUrl>http://dns.api.rackspacecloud.com/v1.0/1234/status/34c0160a-6109-4b61-9ea4-1f0513df031b?showDetails=true</callbackUrl>
        <status>COMPLETED</status>
        <requestUrl>http://dns.api.rackspacecloud.com/v1.0/1234/domains</requestUrl>
        <verb>POST</verb>
        <request>
        </request>
        <response xsi:type="domains" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <domain id="2764458" accountId="440369" name="example.com" ttl="3642" emailAddress="hostmaster@example.com" updated="2011-08-29T15:49:53-05:00" created="2011-08-29T15:49:53-05:00">
                <nameservers>
                    <nameserver name="ns.rackspace.com"/>
                    <nameserver name="ns2.rackspace.com"/>
                </nameservers>
            </domain>
        </response>
    </asyncResponse>
</asyncjobsstatus>

Example: Get detailed status for all jobs response: JSON

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

{
  "totalEntries" : 12,
  "asyncResponses" : [ {
    "status" : "COMPLETED",
    "verb" : "DELETE",
    "jobId" : "1ada58ab-f413-4d7e-a139-19c96eaea8b2",
    "callbackUrl" : "http://dns.api.rackspacecloud.com/v1.0/1234/status/1ada58ab-f413-4d7e-a139-19c96eaea8b2?showDetails=true",
    "requestUrl" : "http://dns.api.rackspacecloud.com/v1.0/1234/domains/2764176"
  }, {
    "status" : "COMPLETED",
    "request" : "\n\t\t",
    "verb" : "POST",
    "jobId" : "34c0160a-6109-4b61-9ea4-1f0513df031b",
    "callbackUrl" : "http://dns.api.rackspacecloud.com/v1.0/1234/status/34c0160a-6109-4b61-9ea4-1f0513df031b?showDetails=true",
    "requestUrl" : "http://dns.api.rackspacecloud.com/v1.0/1234/domains",
    "response" : {
      "domains" : [ {
        "name" : "example.com",
        "id" : 2764458,
        "updated" : "2011-08-29T20:49:53.000+0000",
        "nameservers" : [ {
          "name" : "ns.rackspace.com"
        }, {
          "name" : "ns2.rackspace.com"
        } ],
        "accountId" : 440369,
        "ttl" : 3642,
        "emailAddress" : "hostmaster@example.com",
        "created" : "2011-08-29T20:49:53.000+0000"
      } ]
    }
  } ]
}
Previous Supported Record Types
Next IP Address Support
Developer Network
  • Developer Center
  • API Documentation and User Guides
  • SDKs
  • Rackspace How-To
Blogs
  • Technical Blog
  • Rackspace Blog
  • Solve: Thought Leadership
Other Information
  • Customer Stories
  • Events
  • Programs
  • Careers
  • Style Guide for Technical Content
©2020 Rackspace US, Inc.
  • ©2020 Rackspace US, Inc.
  • About Rackspace
  • Privacy Statement
  • Website Terms
  • Trademarks