openstack team mailing list archive

[Bryan Taylor <btaylor@xxxxxxxxxxxxx>]

On 12/21/2011 05:02 AM, Monty Taylor wrote:
> On 12/20/2011 07:00 PM, Bryan Taylor wrote:
> Version APIs for compatability, not release tracking.
> I could not agree with this more strongly. Like, really, really, really
> strongly.
Strong feelings are not a technical reason.

> > Clients should
> > couple only to major numbers. Media types should have their own
> > independent version counters that use major only.
> >
> > Minor (and bugfix, which is part of minor) should be design time
> > constructs only, basically to name feature seats. Docs, WADL, XSDs, JSON
> > schemas use major+minor.
> I would suggest taking at least learning something from libtool. libtool
> does this stuff really well if you pay attention to the rules. They are
> as follows:
Libtool is not a  web service API. I don't see the analogy here. It's a 
fine tool for what it does -  encapsulating shared software libraries.
> A version consists of a triple: current:revision:age
>
> Current should be increased if interfaces have been added, removed or
> changed
> Revision should be incremented if source code has changed, and should be
> set to zero if current is incremented
> Age should be incremented if interfaces have been added. It should be
> set to zero if interfaces have been removed or changed.
I think you are intermixing code versioning with web service API 
versioning. This would be a fine way to version an implementation like 
Compute, which is wholely different from versioning the compute API. The 
whole point of web services is to hide implementation details that live 
in source code. Think how awful it would be if feed APIs renumbered 
every time the implementation changed. Blog reading software would break 
so often it would be unusable. The API version exists solely to allow 
clients to identify what it is they couple to. They don't want to couple 
to your source code.
> So you have two different things you're tracking - what is the state of
> the interface, and also has the underlying implementation of the
> interface changed. (in theory, two different versions of implementations
> of the v1 interface should be the same - but you _might_ want to be
> paranoid about it, so it's nice to know if it's happened)
>
> The range of API supported by a thing with that version information is
> current-age. For example:
>
> 1:0:0 - initial import - this supports interface version 1.
> 1:1:0 - bug fix in something - this supports interface version 1.
> 2:0:1 - added some interface methods - this supports interface versions
> 1 and 2 (code written to use 1:0:0 or 1:1:0 can safely assume this one
> will work)
> 3:0:0 - removed support for interface versions 1 and 3. supports
> interface version 3 only (removing interface elements essentially always
> need for a consumer to go through and make sure that they still work)
This would be a fine way to version the core openstack implementation of 
Compute, but not the Compute API itself as every time you fix a bug, 
clients will see the version number change and have to touch code.

We don't renumber the HTTP spec version every time a web server fixes a 
bug or rewrites code. Atom doesn't renumber everytime somebody 
implements a new library for it. Keep the versions of the API and the 
implementation (of which may be multiples) separate.

It's a fairly straightfoward set of rules that handle description of
many of the things below. (the scheme and rules are also already being
used by massive amounts of software)

Yes, and that's where it should be applied -- to software. The web is 
not software and web service APIs have different configuration 
management needs.
> FWIW