Open Stack

Nottingham's RFC is exceptionally well documented. I would be strongly against Marconi moving from that RFC to any other format unless the alternative was equally well documented. If they were equally well documented, then I would be neutral on changing it.

More importantly, if a project is providing discoverability for their API and recommending the use of that to clients, the primary unit and integration tests for the service need to use the discovery mechanism. It doesn't help to provide "discoverability" if the implementation doesn't actually provide working links in the service descriptor (regardless of the specific format used).

Sam

-----Original Message-----
From: Flavio Percoco [mailto:flavio at redhat.com] 
Sent: Tuesday, November 26, 2013 2:47 AM
To: OpenStack Development Mailing List (not for usage questions)
Cc: Jorge Williams
Subject: Re: [openstack-dev] [Keystone][Marconi][Oslo] Discoverable home document for APIs (Was: Re: [Nova][Glance] Support of v1 and v2 glance APIs in Nova)

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?

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.


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

Cheers,
FF

--
@flaper87
Flavio Percoco