[openstack-dev] [Keystone][Marconi][Oslo] Discoverable home document for APIs (Was: Re: [Nova][Glance] Support of v1 and v2 glance APIs in Nova)

Dolph Mathews dolph.mathews at gmail.com
Tue Nov 26 16:57:02 UTC 2013

On Tue, Nov 26, 2013 at 2:47 AM, Flavio Percoco <flavio at redhat.com> wrote:

> On 25/11/13 16:50 -0600, Dolph Mathews wrote:
>> On Mon, Nov 25, 2013 at 2:41 AM, Flavio Percoco <flavio at redhat.com>
>> wrote:
>>    On 25/11/13 09:28 +1000, Jamie Lennox wrote:
>>        So the way we have this in keystone at least is that querying GET /
>>        will
>>        return all available API versions and querying /v2.0 for example
>> is a
>>        similar result with just the v2 endpoint. So you can hard pin a
>> version
>>        by using the versioned URL.
>>        I spoke to somebody the other day about the discovery process in
>>        services. The long term goal should be that the service catalog
>>        contains
>>        unversioned endpoints and that all clients should do discovery. For
>>        keystone the review has been underway for a while now:
>>        https://review.openstack.org/#/c/38414/ the basics of this should
>> be
>>        able to be moved into OSLO for other projects if required.
>>    Did you guys create your own 'home document' language? or did you base
>>    it on some existing format? Is it documented somewhere? IIRC, there's
>>    a thread where part of this was discussed, it was related to horizon.
>>    I'm curious to know what you guys did and if you knew about
>>    JSON-Home[0] when you started working on this.
>> It looks like our multiple choice response might predate Nottingham's
>> proposal,
>> but not by much. In keystone, it's been stable since I joined the project,
>> midway through the diablo cycle (summer 2011). I don't know any more
>> history
>> than that, but I've CC'd Jorge Williams, who probably knows.
>> I really like Nottingham's approach of adding relational links from the
>> base
>> endpoint, I've been thinking about doing the same for keystone for quite a
>> while.
> As crazy as it sounds, have you guys considered migrating to
> Nottingham's approach?
It only sounds crazy because I have no idea how to "migrate" an unversioned
endpoint :) Skimming through his proposal, it looks like it might actually
be compatible with ours to include side by side? If so, we could support
both for a couple releases before moving on.

Does this proposal have much traction outside the OpenStack community? (and
how much traction does it have within the community already?)

> We picked this approach because we didn't want to invent it ourselves
> and this happens to have a well defined RFC as well.
> If there's something Nottingham's proposal lacks of, I think we could
> provide some feedback and help making it better.
>>    We used json-home for Marconi v1 and we'd want the client to work in a
>>    'follow your nose' way. Since, I'd prefer OpenStack modules to use the
>>    same language for this, I'm curious to know why - if so - you
>>    created your own spec, what are the benefits and if it's documented
>>    somewhere.
>> Then why didn't Marconi follow the lead of one of the other projects? ;)
> LOOOL, I knew you were going to say that. I think I knew about you
> guys having something similar but at some point I most have forgotten
> about it. That being said, the main rationals were:
>    1) Using something documented and known upstream made more sense
>    and it also helps getting more contributions from the community.
>    2) We already knew it, which falls back in point 1.
Hey, you set yourself up! Seriously though, I welcome the innovation.

>  I completely agree though - standardized version discovery across the
>> ecosystem
>> would be fantastic.
> All that being said, I don't think it would be very hard to migrate
> Marconi to something common if we agree that json-home is not good
> enough for OpenStack. Nonetheless, it'd be a shame not to provide
> feedback to Mark Nottingham about it. So far, his approach has been
> good enough for us - but, you know, Marconi is still way too small.
> Is keystone's home schema spec documented somewhere?

It's actually documented as part of the v2.0 API for keystone, although I
really believe it should be it's own API specification (e.g. Nottingham's



We use the same basic structure to serve the multiple choice response and
versioned endpoints:

  GET /
  GET /v2.0/
  GET /v3/

However, the multiple choice response contains the details for both

> Cheers,
> FF
> --
> @flaper87
> Flavio Percoco
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20131126/13418559/attachment.html>

More information about the OpenStack-dev mailing list