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