Zend Server Web API Spotlight: Versioning

      No Comments on Zend Server Web API Spotlight: Versioning

Hey everybody,

One of the nagging problems of APIs everywhere is that of Versioning – the ability of an API to adapt its behavior based on the version requested by the client. The Zend Server Web API confronts the problem of Versioning and strikes a compromise between maintainability and usability. In this post we will go over Zend Server’s particular brand of versioning and its implications on Zend Server’s Web API.

Some history

Zend Server, as a product, has come quite a way since the days of Zend Server 5. We’ve added features, content, new options to existing modules and introduced new elements the user can control in his environment. Along the way, we’ve also introduced the Web API and began expanding its facilities along with the application and its growing feature set. The Web API, today, encompasses all of Zend Server’s available functionality and goes hand-in-hand with every version released.

In the world of API-first applications, this evolution of the Web API invariably means versioning. Note that Versioning is not exactly backwards compatibility – the two concepts are similar and versioning is a way to enable backwards compatibility. Versioning aims to keep the API stable for the client but rarely guarantees behavior.

To date, Zend Server 6 supports 6 versions of the Web API (1.2 – soon 1.7). Had we not prepared for this day, we would have been bogged down in versioning-maddness.

Versioning in Zend Server

The Act of versioning is the separating the API’s prototypes across different versions of the same API. This means that should a user call the same API action on two different versions he may get two different APIs, behaviors and probably different output. Simply put, this means that each Web API action is to be implemented in a sort of matrix – implementation per action per version. Naive simplification but still true and some projects do just this.

The naive option guarantees separation for the user. It also guarantees the API will be increasingly hard to maintain and test. On small APIs that remain stable and unchanged between product versions this may be practical. Zend Server’s Web API which changes almost every version and constantly adds new functionality. The naive approach will quickly devolve into a constant struggle to keep down the amount of code duplication and layers of abstraction.

An observation of the sort of changes we make to the Web API allows us to follow a guideline we dubbed “Soft Versioning”. Initially, our implementation of versioning was indeed an “implementation per action per version”. As time went by we noticed that:

  • There are few changes
  • Not all changes modify output
  • Most of the changes are actually additions
  • Dense mapping of our actions created useless inheritance and code duplication
  • Users who parse our output usually do so regardless of version, they rely on structure instead

In short: our Web API underwent very few real changes to behavior, few changes to existing parameters and few changes to output structure. We mostly added new actions, parameters or added elements to existing output. This observation led us to a new way of versioning: we avoid versioning Web API actions when possible, where “possible” is defined as

As long as we are not explicitly changing mandatory behavior, existing mandatory parameters or removing functionality

What this means for Zend Server

In practice this means that if a Web API action is to be changed, we only create a new implementation of it (a new concrete method or controller) if the changes actually modify behavior in a meaningful way. We consider “meaningful” to be a change that will irrevocably break a user’s reliance on our output or that our action would not answer his expectations consistently.

Should a change be just about adding a new output element, a new (optional) parameter, a new (optional) behavior, then we just modify the existing, latest version to conform. Over time this has led to the Web API changing slightly between versions of Zend Server – not a desirable outcome but a reasonable compromise.

On the flip side, it has saved us countless hours and effort to test, maintain and develop the Web API. Hours we then invested back into the UI, allowing us to complete features faster and more easily than in the past.

What this means for you

The Web API is a fairly simple API all things considered – it has many actions and variety but these actions are consistent in structure and behavior across the system. The nature of Soft Versioning means that in some cases output you receive may suddenly spawn new elements. If you’re using a JSON or XML parser and do not rely on order in a modular data structure chances are you will not even notice anything’s changed.

Should you encounter a gross modification of behavior or output that “creeped” into our output payload, it will definitely not be intentional and reporting it will have it fixed back into order quickly.

If you haven’t dug into the Web API yet, I recommend you take a look at a few clients for PHP that have already been written so that some of the work is already done:

Note that all of these libraries are continuously maintained and may change. Some of these libraries may require periodic updates, other are simplistic but provide very little in the way of output handling.

Join me next time as we take a look at how Version Negotiation works in Zend Server Web API.