API Versioning Negotation
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.
