4.4. Responses

4.4.1. Response Formats: XML and JSON

CloudStack supports two formats as the response to an API call. The default response is XML. If you would like the response to be in JSON, add &response=json to the Command String.

Sample XML Response:

     <listipaddressesresponse> 
        <allocatedipaddress>
        <ipaddress>192.168.10.141</ipaddress> 
        <allocated>2009-09-18T13:16:10-0700</allocated> 
        <zoneid>4</zoneid> 
            <zonename>WC</zonename> 
            <issourcenat>true</issourcenat> 
        </allocatedipaddress>
     </listipaddressesresponse>

Sample JSON Response:

        { "listipaddressesresponse" : 
          { "allocatedipaddress" :
            [ 
              { 
                "ipaddress" : "192.168.10.141", 
                "allocated" : "2009-09-18T13:16:10-0700",
                "zoneid" : "4", 
                "zonename" : "WC", 
                "issourcenat" : "true" 
              } 
            ]
          } 
        }

4.4.2. Maximum Result Pages Returned

For each cloud, there is a default upper limit on the number of results that any API command will return in a single page. This is to help prevent overloading the cloud servers and prevent DOS attacks. For example, if the page size limit is 500 and a command returns 10,000 results, the command will return 20 pages.

The default page size limit can be different for each cloud. It is set in the global configuration parameter default.page.size. If your cloud has many users with lots of VMs, you might need to increase the value of this parameter. At the same time, be careful not to set it so high that your site can be taken down by an enormous return from an API call. For more information about how to set global configuration parameters, see "Describe Your Deployment" in the Installation Guide.

To decrease the page size limit for an individual API command, override the global setting with the page and pagesize parameters, which are available in any list* command (listCapabilities, listDiskOfferings, etc.).

Both parameters must be specified together.
The value of the pagesize parameter must be smaller than the value of default.page.size. That is, you can not increase the number of possible items in a result page, only decrease it.

For syntax information on the list* commands, see the API Reference.

4.4.3. Error Handling

If an error occurs while processing an API request, the appropriate response in the format specified is returned. Each error response consists of an error code and an error text describing what possibly can go wrong. For an example error response, see page 12.

An HTTP error code of 401 is always returned if API request was rejected due to bad signatures, missing API Keys, or the user simply did not have the permissions to execute the command.