API Versioning Negotiation

As you perform an API call, it should specify its currently used API version as part of the Zend Server API media type in the Accept HTTP header. For example, sending a request using API version 3.0 should include the following Accept header in the request:

Accept: application/vnd.zend.serverapi+xml;version=3.0

If the server supports the specified API version, it will handle the request and respond in the appropriate format, matching the specified API version. The response format and API version will be specified using the Content-type response header:

Content-type: application/vnd.zend.serverapi+xml;version=3.0

If the server is not compatible with the API version being used, the server will return an HTTP 406 Not Acceptable”response, with supported version content types listed as part of the <errorData> XML.

Usage Example

Example:

<?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>
<errorData>
<errorCode>unsupportedApiVersion</errorCode>
<errorMessage> Client API version not supported by this server </errorMessage>
<supportedApiVersions>
      application/vnd.zend.serverapi+xml;version=1.0,
      application/vnd.zend.serverapi+xml;version=1.1,
      application/vnd.zend.serverapi+xml;version=2.0
</supportedApiVersions>
</errorData>
</zendServerAPIResponse>

You can then choose to switch to a different API version, or give up and issue a failure message to the end user.

Note:

The Accept request header, while highly recommended, is optional. If you do not specify the Accept header, the server will fall back to using the oldest API version supported by the server for the particular action requested.

Other available response formats are JSON which generally follows XML responses in structure and behavior.

Note:

Some specific and explicitly noted WebAPI actions return a different payload from that specified in the accept header. Such actions may return a binary file or could be prohibited from returning a particular format such as json. In these cases the correct request format will be noted in the documentation and an appropriate error provided.