Open Stack

On Sun, Apr 26, 2015 at 7:48 PM, Tom Fifield <tom at openstack.org> wrote:

> On 27/04/15 08:36, Anne Gentle wrote:
> >
> >
> > On Sun, Apr 26, 2015 at 7:32 PM, Tom Fifield <tom at openstack.org
> > <mailto:tom at openstack.org>> wrote:
> >
> >     On 27/04/15 08:29, Anne Gentle wrote:
> >     >
> >     >
> >     > On Sun, Apr 26, 2015 at 7:24 PM, Tom Fifield <tom at openstack.org
> <mailto:tom at openstack.org>
> >     > <mailto:tom at openstack.org <mailto:tom at openstack.org>>> wrote:
> >     >
> >     >     Hi,
> >     >
> >     >     This isn't my patch, but I'm just pulling this on to the
> mailing list
> >     >     since I saw it languishing:
> https://review.openstack.org/#/c/155329/ :)
> >     >
> >     >     In this patch, the sample json files are updated for new
> things that are
> >     >     coming in Kilo. However, as Anne notes: "This site is updated
> >     >     continually, but it seems like these JSON examples won't be
> accurate
> >     >     until the next version comes out. What should we do in this
> case?"
> >     >
> >     >     Then it's noted that we have folks using trunk, etc.
> >     >
> >     >     So - API site versioning - how do we solve it for "all APIs
> and those
> >     >     with extensions" ?
> >     >
> >     >
> >     > This needs blueprint-level design decisions and a spec. Ideally
> we'll
> >     > rid ourselves of WADL in the design as well.
> >     >
> >     > I'd like to take this on next release and I'm looking for
> collaborators.
> >     > Extensible APIs make versioning especially difficult.
> >
> >     Of course - this is just an attempt to start the brainstorming, not
> fix
> >     the specific patch :)
> >
> >
> >
> > Absolutely!
> >
> > Ideas I'd like to poke at:
> > Migrate WADL content to Swagger, please look at
> > WADL2Swagger github.com/rackerlabs/wadl2swagger
> > <http://github.com/rackerlabs/wadl2swagger>
> > Migrate WADL content to RAML
> > Move all API content into project repos, aggregate those into an API
> > reference site
>
> Very nice :) Have you got as far as looking at how swagger does API
> versioning yet?
>
> A quick google found:
>
> http://stackoverflow.com/questions/22224308/servicestack-swagger-ui-and-api-version-number
>
> which looks like we'd have to spin up some different AppHosts for each
> API version. Shouldn't be too hard with our automation, and maybe it's
> improved in the intervening year.
>
> So, here's a question:
>
> Do people prefer:
> * A single API reference per release (eg Kilo - not api release)
> * A single API reference per API version that has 'available in release
> X' labels per API call, where methods aren't commonly available.
>

I think it's this. Steve Gordon has mentioned it in the past, Steve, is
this what your users would prefer?


> * Something else
>

> > If anyone is interested, let's talk at the Summit at the API docs
> > session whenever that lands.
> > Anne
> >
> >
> > --
> > Anne Gentle
> > annegentle at justwriteclick.com <mailto:annegentle at justwriteclick.com>
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150426/0806946a/attachment-0001.html>