Response Format

In this Topic ShowHide

About

API HTTP response messages use standard HTTP response codes to designate high-level status (success, failure, etc.) and simple XML payload in the response body to provide additional method specific data or specific error messages.

HTTP Response Codes

Zend Server Web API operations will return standard HTTP response codes in order to indicate overall success or failure. In case of an error, the HTTP status code may further indicate the nature of the problem, and a specific error code contained in the response body will indicate the specific nature of the error.

The following HTTP response codes may be used:

• 200 OK - The operation has completed successfully.
• 202 Accepted - The operation was accepted and is being processed, but is not complete yet.
• 4xx - HTTP status codes between 400 and 499 are used to designate a client-side error. For example, a missing request parameter or an authentication error.
• 5xx - HTTP status codes between 500 and 599 are used to designate a server-side error. For example, a temporary locking issue or an unexpected error in the server operation.

Additional information about HTTP response codes for error responses is available in Error Responses, as well as in the documentation for each method.

HTTP Response Headers

The following HTTP response headers will be included in API responses:

• Content-type - Unless stated otherwise, these will be “application/vnd.zend.serverapi+xml; version=<API version>”. For more information about API versions see API Versioning Negotiation.

HTTP Response Body

The Web API HTTP response body will almost always contain an XML document of the following format:

<?xml version="1.0" encoding="UTF-8"?>
<zendServerAPIResponse
  xmlns=“http://www.zend.com/server/api/1.0”>
    
  <requestData>
    <apiKeyName>angel.eyes</apiKeyName>
    <method>clusterGetServerStatus</method>
  </requestData>
  
  <responseData>
    [response data here...]
  </responseData>
</zendServerAPIResponse>

 

All API responses are enclosed in <zendServerAPIResponse> tags, and contain two sections: <requestData> which includes some reference information about the request; and <responseData> which includes the response data.

The content of the <responseData> section differs depending on the specific method called. Refer to the method's specific documentation for additional information.

In error responses, the <responseData> section is replaced with an <errorData> section. See Error Responses for additional information.

Some Web API methods will not return an XML document in case of a successful operation - specifically, methods that export large amounts of binary data such as the configurationExport method. In such cases, this is specifically indicated in the method's documentation. Note that you can check the value of the Content-type response header in order to know in advance what kind of content to expect in the response.

Error Responses

In a response representing an error, the <responseData> XML section is replaced with the <errorData> XML section, which has the following format:

<errorData>
  <errorCode>serverDoesNotExist</errorCode>
  <errorMessage>A server with the specified ID does not exist in the cluster</errorMessage>
</errorData>

Where:

• <errorCode> is a short alphanumeric constant string that represents the specific error.
• <errorMessage> is a human readable, native language explanation of the error.

In addition, some error responses may include additional elements in the <errorData> container, with additional information relevant to the specific error.

Generic Error Codes

The following generic error responses are possible for any operation:

Refer to the documentation of a specific method for details about additional possible errors specific to each method.