Open Stack

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