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

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

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

<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" : "[email protected]"  
        } \]  
        }  
</request>  
<response>  
        <domains>
          <id>12345</id>
          <accountId>1234</accountId> 
          <name>example.com</name>
          <ttl>3600</ttl>
          <emailAddress>[email protected]</emailAddress>
          <updated>2011-08-23T14:02:54-05:00</updated>
          <created>2011-08-23T14:02:54-05:00</created>
          <nameservers>  
           <name>ns.rackspace.com</name>  
          </nameservers>  
          <nameservers>
           <name>ns2.rackspace.com</name>  
          </nameservers>
        </domains>  
</response>

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\" : \"[email protected]\"\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" : "[email protected]",  
      "created" : "2011-08-23T19:02:54.000+0000"  
    } ]  
  }  
}

ℹ️
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: 190

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

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

<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" : "[email protected]"  
        } ]  
        }  
</request>  
<error code="400">  
    <message>Validation failed.</message>  
    <details>Zone with domain name example.com already exists.</details>  
</error>

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" : "Validation failed.",  
    "code" : 400,  
    "details" : "Zone with domain name example.com already exists."  
  },  
  "request" : "{\n  \"domains\" : \[ {\n  \"name\" : \"example.com\",\n  \"emailAddress\" : \"[email protected]\"\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"  
}

ℹ️
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: 571

<totalEntries>12</totalEntries> 
<asyncResponses>  
        <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>  
</asyncResponses>  
<asyncResponses>  
        <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>  
</asyncResponses>

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

<totalEntries>12</totalEntries>
<asyncResponses>  
        <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>  
</asyncResponses>  
<asyncResponses>  
        <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>
            <domains>
              <id>2764458</id>
              <accountId>440369</accountId> 
              <name>example.com</name>
              <ttl>3642</ttl>
              <emailAddress>[email protected]</emailAddress>
              <updated>2011-08-29T15:49:53-05:00</updated>
              <created>2011-08-29T15:49:53-05:00</created>
              <nameservers>  
               <name>ns.rackspace.com</name>   
              </nameservers> 
              <nameservers>  
               <name>ns2.rackspace.com</name>   
              </nameservers>  
            </domains>
        </response>
</asyncResponses>

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" : "[email protected]",  
        "created" : "2011-08-29T20:49:53.000+0000"  
      } ]  
    }  
  } ]  
}

Synchronous and asynchronous responses

ℹ️
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.

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

ℹ️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.

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

ℹ️
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.

ℹ️
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.