Open Stack

On Thu, 13 Feb 2014 15:54:23 -0500
Sean Dague <sean at dague.net> wrote:

> On 02/13/2014 09:45 AM, Dean Troyer wrote:
> > FWIW, an early proposal to address this, as well as capability
> > discovery, still lives
> > at https://etherpad.openstack.org/p/api-version-discovery-proposal.
> >  I've lost track of where this went, and even which design summit
> > this is from, but I've been using it as a sanity check for the
> > discovery bits in OSC.
> > 
> > On Thu, Feb 13, 2014 at 6:50 AM, Jamie Lennox
> > <jamielennox at redhat.com <mailto:jamielennox at redhat.com>> wrote:
> > 
> >     6. GET '/' is unrestricted. GET '/vX' is often token restricted.
> > 
> > 
> >     Keystone allows access to /v2.0 and /v3 but most services give a
> >     HTTP Unauthorized. This is a real problem for discovery because
> > we need to be able to evaluate the endpoints in the service
> > catalog. I think we need to make these unauthorized.
> > 
> > 
> > I agree, however from a client discovery process point-of-view, you
> > do not necessarily have an endpoint until after you auth and get a
> > service catalog anyway.  For example, in the specific case of
> > OpenStackClient Help command output, the commands listed may depend
> > on the desired API version.  To get the endpoints to query for
> > version support still requires a service catalog so nothing really
> > changes there.
> > 
> > And this doesn't even touch on the SC endpoints that include things
> > like tenant/project id...
> >  
> > 
> >     Please have a look over the wiki page and how it addresses the
> > above and fits into the existing schemes and reply with any
> > comments or problems that you see. Is this going to mess with any
> > pre-existing clients?
> > 
> > 
> > * id: Let's either make this a real semantic version so we can
> > parse and use the major.minor.patch components (and dump the 'v')
> > or make it an identifier that matches the URL path component.
> > Right now 
> > 
> > * updated: I think it would be a friendly gesture to update this for
> > unstable changes as the id is likely to not be updated mid-stream.
> >  During debugging I would want to be able to verify exactly which
> > implementation I was talking to anyway.
> 
> So, I'd actually like to extend this a bit differently, and add a
> micro version to the API as a normal part of our flows.
> https://review.openstack.org/#/c/73090/ is an early sketch of this.
> 
> GET /
> 
> Content-Type: application/json
> Content-Length: 327
> Date: Thu, 13 Feb 2014 20:51:48 GMT
> 
> {
>     "versions": [
>         {
>             "status": "CURRENT",
>             "updated": "2011-01-21T11:33:21Z",
>             "rev": "2.0000",
>             "id": "v2.0",
>             "links": [
>                 {
>                     "href": "http://localhost:8774/v2/",
>                     "rel": "self"
>                 }
>             ]
>         },
>         {
>             "status": "EXPERIMENTAL",
>             "updated": "2013-07-23T11:33:21Z",
>             "rev": "2.0900",
>             "id": "v3.0",
>             "links": [
>                 {
>                     "href": "http://localhost:8774/v3/",
>                     "rel": "self"
>                 }
>             ]
>         }
>     ]
> }
> 
> And on hitting something under the /v3/ tree:
> 
> Content-Type: application/json
> X-Osapi-Version: 2.0900

So is that a typo there and it should be 3.0900?

> Content-Length: 651
> X-Compute-Request-Id: req-6a4ed4f0-07e4-401a-8315-8d114005c6ab
> Date: Thu, 13 Feb 2014 20:51:48 GMT
> 
> {
>     "version": {
>         "status": "EXPERIMENTAL",
>         "updated": "2013-07-23T11:33:21Z",
>         "links": [
>             {
>                 "href": "http://localhost:8774/v3/",
>                 "rel": "self"
>             },
>             {
>                 "href":
> "http://docs.openstack.org/api/openstack-compute/3/os-compute-devguide-3.pdf",
> 
>                 "type": "application/pdf",
>                 "rel": "describedby"
>             },
>             {
>                 "href":
> "http://docs.openstack.org/api/openstack-compute/3/wadl/os-compute-3.wadl",
>                 "type": "application/vnd.sun.wadl+xml",
>                 "rel": "describedby"
>             }
>         ],
>         "rev": "2.0900",
>         "media-types": [
>             {
>                 "base": "application/xml",
>                 "type":
> "application/vnd.openstack.compute+xml;version=3" },
>             {
>                 "base": "application/json",
>                 "type":
> "application/vnd.openstack.compute+json;version=3" }
>         ],
>         "id": "v3.0"
>     }
> }
> 
> 
> that would then let us return a pretty fine grained global API version
> that included the non breaking backwards compatible changes. Nova is
> going to version extensions this time around, but a global increment
> would be much better for a consistent view of the world.

So one question I have around a global version is what happens when we
have the following situation:

- Extension (not core) A is bumped to version 3, global version bumped
  to 3.01
- Extension B (not core) is bumped to version 6, global version bumped
  to 3.02

but the deployer for $REASONS (perhaps stability/testing/whatever)
really wants to deploy with version 2 of A but version 6 of B. 

With versioning just on the extensions individually they're ok, but
I don't think there's any real sane way to get a global micro version
calculated for this scenario that makes sense to the end user.

Chris