openstack team mailing list archive

[Bryan Taylor <btaylor@xxxxxxxxxxxxx>]

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.

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

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