Open Stack

> On Tue, 2011-12-20 at 10:35 -0500, Brian Waldon wrote:
> 
>> So there obviously isn't one clear way to version a RESTful API. Not
>> every API is created equal, and therefore doesn't need the same
>> capabilities in its versioning mechanism. At this point, it is
>> important to determine what specifically the Compute API needs:
>> 
>> - Our versioning mechanism should not hinder progress within the underlying implementation
>> - We need to be able to iterate on the design of our API without being tied down
>> - It needs to be simple to use from the point of view of API developers AND language bindings authors
>> 
>> 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
>> - Expose version of response in Content-Type header (application/vnd.openstack.compute.v3+json)
>> - Form request with version in Accept/Content-Type headers
>> - If no version is provided in request, default to stable
>> - If an unsupported version is requested, provide a 300 Multiple Choices response w/ list of available versioned mimetypes
>> - Provide a mechanism that can communicate all supported mimetypes (versions)
> 
> There are clearly lots of different approaches that could be taken and
> this looks as reasonable as any other.
> 
> Just a couple of points I'd make:
> 
>  - Versioning is important, but I'd prefer us to place more emphasis 
>    on how to design the API such that we can continue to expand the 
>    API in compatible ways for a decent period without introducing a 
>    new major version e.g.

Absolutely agree.

>      - capability discovery - clients should not assume the API 
>        supports a given feature, but should query for its availability 
>        at runtime

Do you see the current extensions mechanism as a complete solution to this problem?

>      - opaque URI structure - by requiring clients to navigate links 
>        in the hypertext documents returned by the server, you can 
>        change things around without breaking well-written clients. 
>        Basically, a good rule is that a client should never need to
>        construct a URI

I think the missing link here is a root resource that provides links to get clients into top-level resources (servers, images, etc). Right now, the only client I've worked on doesn't follow links (python-novaclient).

>      - versioning of resources - if we versioned individual resources, 
>        we could introduce a new incompatible version of a single 
>        resource without affecting users of other resources.

So I'm not completely sold here, but the mechanism I have proposed is open-ended enough that we could do this if we have enough reason to do so. I think this adds a lot of complexity from the client's point of view once they have to track multiple versions of multiple resources.

>  - The whole question of media types is worthy of a long discussion, 
>    e.g.
> 
>      https://fedorahosted.org/pipermail/rhevm-api/2010-April/thread.html#94
>      https://www.redhat.com/archives/rest-practices/2010-April/thread.html#00004
> 
>    Those discussions run the whole gamut of the topic, from whether 
>    media types should be fine or coarse grained, how to make 
>    compatible changes in XML, schema implications, URI based 
>    versioning schemes, etc.
> 
>    If we go with media type based versioning, it would definitely make 
>    more sense as a parameter e.g.
> 
>      Accept: application/vnd.openstack.compute+json;version=3
> 
>    Also, I'd support versionless application/xml and application/json 
>    to make things dirt simple for trivial one-off clients.

Yep, I'm for a default (unversioned media type). However, I'm against using version as a param. I will admit I've only looked at webob, but it seems like it is uncommon for libraries to parse accept params other than 'q' and 'level'.

>  - The big argument for URI based versioning is that not all clients 
>    (e.g. browsers) can participate in content type negotiation. I'm 
>    not convinced that's a huge issue, though.

Yeah, I don't want to have my hands tied by this requirement. I think we can define defaults to allow browsers to participate, but that's where I would draw the line.

Brian