What constitutes a version change?

Recently, in the ROA technical group, we discussed what constitutes a version change in our RESTful services. Many of us have adopted the versioning convention of embedding a version integer in the URI as supported in the Richardson and Ruby book


So when do we need to change this integer? As we add new data elements to our fledgling services, we are concerned about a proliferation of versions, and in particular, URI’s. Do we need to change URI’s with the addition of each new element? To do this too often seems to add unnecessary complexity and maintenance cost. Instead we have decided that minor changes that are “additive” do not necessitate an integer version change and consequently do not require a change to the URI.

By “additive” changes, we mean changes that wouldn’t break xpath queries based upon the class attribute:


as opposed to a queries based upon the ordinal relationship of elements


(We consider the use of queries based on the class attribute a better development practice.)

One concern is that even if we don’t break clients with a version change, how do we communicate the change. We are recommending the inclusion of a programmatically parsable xhmtl version element in the root of each service that describes a fuller version, perhaps with major, minor, revision, and build.

<div>Service Code version:
<span class="service_code_version"></span></div>

That should allow for programmatic detection of version changes. And, of course, we still advocate application support email lists to communicate any change in service contract.

What do others think?

  1. #1 by Scott Bush - May 29th, 2009 at 09:15

    I agree with Rupert in that version integers shouldn’t change unless something major occurs. Certainly, any update that would break existing apps (due to an API change or something along those lines) deserves a new version.
    As for incremental additions, the service code version should be adequate–with an up-to-date reference–to inform developers what data they can access. Incrementing the version integer based on additions to the web services should only happen when those additions are sufficient enough to warrant it. What constitutes “sufficient” is another question…

Comments are closed.