Zend Server WebAPI spotlight: Version Negotiation Explained

Hey everybody,

As discussed earlier, Zend Server’s Web API has multiple versions – with each new feature and option new Web API actions are created and existing ones gain new meaning and behaviors. While Zend Server may be forging ahead, it is shifting your infrastructure along with it – which may not be desirable. The Web API’s specification allows for this by giving the client control over which version is used to execute its requests. This process of selecting a version is called “Version Negotiation”.

Accept Header for Version Negotiation

Version Negotiation the static picture

When communicating with the Web API the user may use the Accept header to specify the version he wishes to use (hereon, the Requested Version). This is an important part of the header as it directly reflects on the expected behavior of the action. Note that you may skip requesting a version. In such a case Zend Server selects the earliest available version for the action.

When a version is requested, Zend Server does its best to find the earliest (smallest), closest version of the action that exists.

Lets break this down:

• The requested version must be greater or equals to the earliest (smallest) version of the requested Web API action. Otherwise, Zend Server will return an error.
• If the requested version is exactly the same as an implemented version (any of those) of the requested action, Zend Server just uses the requested version.
• When the requested version isn’t exactly matched to an implemented version, Zend Server attempts to find the closest match which is still smaller than the requested version.

Let us observe a few examples for this to make more sense:

The action exampleWebapiRequest was implemented in three different versions – 1.2, 1.4 and lately in 1.7.

1. Should our request specify the version 1.0, an error will be returned
2. Should our request not specify any version, version 1.2 will always be selected
3. Should our request specify the version 1.4, version 1.4 will be selected
4. Should our request specify the version 1.5, version 1.4 will still be selected

Continuing with the above example, our corresponding Accept headers will look like so:

1. application/vnd.zend.serverapi;version=1.0
2. application/vnd.zend.serverapi
3. application/vnd.zend.serverapi;version=1.4
4. application/vnd.zend.serverapi;version=1.5

Summary

Version negotiation is a dark, slightly mysterious corner of the Web API – now hopefully de-mystefied for your use and convenience. We provide this feature aiming to both provide you with a cross-version stable platform as well as give you the power to pick and choose which version is used for every request you make.

When considering version negotiation it is also important to keep in mind what was discussed in Spotlight: Versioning in regards to Zend Server’s Soft Versioning policies.

Read more : Zend Server WebAPI spotlight: Version Negotiation Explained