Open Stack

Hi Garbiel

On Thu, 2013-05-02 at 00:46 +0000, Gabriel Hurley wrote:
> Based on input from several of the PTLs (and others), I'd like to
> propose the following outline for how version discovery should be
> handled across heterogeneous clouds:
> 
> https://etherpad.openstack.org/api-version-discovery-proposal
> 
> Further discussion is absolutely welcome, and I would like to propose
> it as a topic for review by the Technical Committee at the next
> meeting since it involves a significant cross-project standardization
> effort.

This definitely looks like a nice step forward and would be great to
have it done cross-project.

This is a bit of a side-track but ... I've been around this project a
while now, but I admit to still being pretty confused about our approach
to API versioning. Are extensions really our only way of adding new
capabilities to an API version in a backwards compatible way?

And are extensions really our only way of allowing an API capability to
be optional?

I'd like to see us introducing new API versions a lot less regularly,
but still being able to add new capabilities (and optional capabilities)
in a backwards compatible and client-queryable way.

Some options for doing that:

  * We allow minor versions with new features; clients know what 
    features are supported in minor versions and expose capabilities to 
    users based on the queried versions

  * We add a 'GET /capabilities' which returns a document describing 
    which features this endpoints support - a feature could be optional 
    because it was added in a new version or because not all 
    deployments would be configured with it enabled. This would allow 
    clients to be able to query for features, rather than having a 
    hard-coded understanding of which minor versions support which
    features.

  * We adopt a more HATEOAS model where a client basically never 
    constructs a URL - everything can be reached via links in the 
    hypertext we return. If an endpoint doesn't support a given 
    feature, it just never includes a link to that feature in the 
    hypertext.

An example of the first approach:

  https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.0/html-single/REST_API_Guide/index.html#sect-REST_API_Guide-Capabilities-Example

  <capabilities>
      <version minor="0" major="3">
          <current>true</current>
          <features>
              <transparent_hugepages/>
          </features>
          <cpus>
              <cpu id="Intel Conroe Family">
                  <level>3</level>
              </cpu>
   ....

   (ignore the version number there, it's not what you think it is)

and the second approach:

  https://access.redhat.com/site/documentation/en-US/Red_Hat_Enterprise_Virtualization/3.0/html-single/REST_API_Guide/index.html#sect-REST_API_Guide-Common_Features-Resources-Actions

  <resource>
      ...
      <actions>
          <link rel="start" href="/api/collection/resource_id/start"/>
          <link rel="stop" href="/api/collection/resource_id/stop"/>
        ...
      </actions>
      ...
  </resource>

Deltacloud's native API also has some of this:

  http://deltacloud.apache.org/api-entry-point.html

  <link href='http://localhost:3001/api/images' rel='images'>
    <feature name='owner_id'/>
  </link>


HTH,
Mark.