openstack team mailing list archive

[Mark McLoughlin <markmc@xxxxxxxxxx>]

Hi Brian,

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.

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

      - 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

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

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

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

Cheers,
Mark.