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

/student/v3/course

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:

/html/body/div/span[@class='foo']

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

/html/body/div[2]/span[3]

(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">3.0.1.26481</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?

2 thoughts on “What constitutes a version change?

  1. Pingback: Architecture Blogs

Comments are closed.