openstack team mailing list archive

[Brian Waldon <brian.waldon@xxxxxxxxxxxxx>]

Comments inline:

On Dec 20, 2011, at 11:03 AM, Julien Danjou wrote:

>> Unsupported Versions
>> - What do you do when a request is made with an unsupported version?
> 
> HTTP 406 ?

We can do that or a 300. I'm proposing 300 so we can be the most helpful, but that may be overkill. Maybe clients won't even parse the response and will just try what they know.

>> With those goals in mind, I would like to propose we adopt the following mechanism:
>> 
>> - Use only major versions
>> - Allow backwards incompatibility between major versions
> 
> So what's the point of not saying that you may not be breaking
> compatibility by adding a minor version usage for just new feature for
> example?

I should have added that I'm against minor versions in the Compute API due to our extensions mechanism. I don't want non-breaking changes in the core API to break existing extensions. It's easier to just add an extension rather than extend the core spec.

>> I would love to hear your feedback on this proposal, however, I'm not really
>> looking to get into a fight about what's more RESTful ;) I know we already
>> have several (slightly different) versioning mechanisms in place, but this
>> is something that can't be wrong. There's still a lot to figure out here,
>> but I think this is a good subset that we can reach an agreement on. In
>> order for OpenStack to be successful, we need to get these foundation pieces
>> right!
> 
> I'm probably getting a little off-topic here, but what about API
> documentation and specification?
> 
> I understand that Keystone is using WADL to specify its API, what's the
> plan for other OpenStack components?


We're planning to support developer docs and provide a wadl. We actually have both of those available as of now (wadl is in the compute-api project and the docs are deployed to docs.openstack.org).

Brian Waldon