You are currently viewing Zend Server 5.x documentation. Click here to view the latest Zend Server online documentation.

You are here: Web API Reference Guide > API Versioning Negotiation

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.


	Related Links: Generic Request/Response Format