Open Stack

On 02/13/2014 08:28 PM, Christopher Yeoh wrote:
> 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?

So actually I was thinking about this as a 2.9000 API, as the
pre-release. We can decide it's really 3.0000 instead.

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

So there remains a question about extensions vs. global version. I think
a big piece of this is anything which is a "core" extension, stops
getting listed as an extension and instead is part of properly core and
using the global version.

How extensions impact global version is I think an open question. But
Nova OS API is actually really weird if you think about it relative to
other cloud APIs (ec2, gce, softlayer). We've defined it not as the Nova
API, but as a small core compute API, and many dozens optional features,
which every deployer makes decisions on what comes and goes.

I agree we need to think through a few things. But I think that if we
get to v3, only to have to do a ton more stuff for v4, and take 2 more
years to get there, we're in a world of hurt. The current model of API
revisions as giant big bangs isn't good for any one. A way to make an
API be able to grow over time, in a backwards compatible way, and some
mechanism to deprecate and remove a feature over time would be much more
advantageous to our consumers.

	-Sean

-- 
Sean Dague
Samsung Research America
sean at dague.net / sean.dague at samsung.com
http://dague.net

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 547 bytes
Desc: OpenPGP digital signature
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20140213/d7712549/attachment.pgp>