openstack team mailing list archive

[Monty Taylor <mordred@xxxxxxxxxxxx>]

On 12/20/2011 07:00 PM, Bryan Taylor wrote:
> 
> Generally, I like the new versioning proposal and see it as simpler. If
> Compute adopts this change and succeeds with it, I'd like to see it
> OpenStack wide. Clients shouldn't have to learn several different
> versioning schemes.

I agree with this.

> My 2 cents on your questions:
> 
> On 12/20/2011 09:35 AM, Brian Waldon wrote:
>> Numbering
>> - Major, minor, bugfix?
> 
> Version APIs for compatability, not release tracking.

I could not agree with this more strongly. Like, really, really, really
strongly.

> 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:

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.

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)

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)

FWIW

>> Backwards Compatibility
>> - At what level do you support backwards compatibility, if at all?
> 
> Two notions: URI structure and data format. Formats can break backwards
> compatibility by bumping a major version number. URI paths should never
> change within the endpoint domain. If you want to restructure them and
> reuse terms in incompatible ways, build a new service at a new domain.
> 
> Within one endpoint domain, if you use /widgets in one release, all
> future releases are stuck with its meaning of that term and location on
> the path. So if I want a new type of widget, I'd have to give it a new
> path name, like /widgetoid or /gadget or /new-widget or whatever.
> 
> There should be a canonical path to resources and if those resources
> represent real world things (like an image, instance, etc...) then it's
> URI should never change.
> 
>> Communication
>> - Version in URI, mimetypes, or both?
> 
> mimetypes only
> 
>> Versions Collection
>> - Provide a complete list of supported versions?
> 
> I'd like to see a service profile resource that says what WADLs and what
> media types the service supports.
> 
>> Unsupported Versions
>> - What do you do when a request is made with an unsupported version?
> 
> Two choices, either is reasonable:
> 300 Multiple Choices
> 406 Not Acceptable
> 
>> Defaults
>> - Allow requests without explicit versions?
> 
> No! Defaulting to the latest causes them to break sooner than they need
> to if you introduce a newer concurrent version. They know what data
> format they coded to, making them state it in the request only makes
> their choice visible.
> 
>> Scope
>> - Do versions apply to the complete API or to subsections? ...or both?
> 
> A version of the WADL specifies a coherent subset of resource types that
> a client can rely on. It says "these resources exist" with an open-world
> assumption. It's Duck Typing for services.
> 
> If the major number doesn't change, you can't remove anything.
> 
> If the major number does change, you might keep some things.
> 
> Extensions have their own WADL and never overlap with the core API.
> 
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp
>