<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Sun, Apr 26, 2015 at 8:00 PM, Anne Gentle <span dir="ltr"><<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote"><div><div class="h5">On Sun, Apr 26, 2015 at 7:48 PM, Tom Fifield <span dir="ltr"><<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span>On 27/04/15 08:36, Anne Gentle wrote:<br>
><br>
><br>
> On Sun, Apr 26, 2015 at 7:32 PM, Tom Fifield <<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a><br>
</span><span>> <mailto:<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a>>> wrote:<br>
><br>
> On 27/04/15 08:29, Anne Gentle wrote:<br>
> ><br>
> ><br>
> > On Sun, Apr 26, 2015 at 7:24 PM, Tom Fifield <<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a> <mailto:<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a>><br>
</span><span>> > <mailto:<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a> <mailto:<a href="mailto:tom@openstack.org" target="_blank">tom@openstack.org</a>>>> wrote:<br>
> ><br>
> > Hi,<br>
> ><br>
> > This isn't my patch, but I'm just pulling this on to the mailing list<br>
> > since I saw it languishing: <a href="https://review.openstack.org/#/c/155329/" target="_blank">https://review.openstack.org/#/c/155329/</a> :)<br>
> ><br>
> > In this patch, the sample json files are updated for new things that are<br>
> > coming in Kilo. However, as Anne notes: "This site is updated<br>
> > continually, but it seems like these JSON examples won't be accurate<br>
> > until the next version comes out. What should we do in this case?"<br>
> ><br>
> > Then it's noted that we have folks using trunk, etc.<br>
> ><br>
> > So - API site versioning - how do we solve it for "all APIs and those<br>
> > with extensions" ?<br>
> ><br>
> ><br>
> > This needs blueprint-level design decisions and a spec. Ideally we'll<br>
> > rid ourselves of WADL in the design as well.<br>
> ><br>
> > I'd like to take this on next release and I'm looking for collaborators.<br>
> > Extensible APIs make versioning especially difficult.<br>
><br>
> Of course - this is just an attempt to start the brainstorming, not fix<br>
> the specific patch :)<br>
><br>
><br>
><br>
> Absolutely!<br>
><br>
> Ideas I'd like to poke at:<br>
> Migrate WADL content to Swagger, please look at<br>
> WADL2Swagger <a href="http://github.com/rackerlabs/wadl2swagger" target="_blank">github.com/rackerlabs/wadl2swagger</a><br>
</span>> <<a href="http://github.com/rackerlabs/wadl2swagger" target="_blank">http://github.com/rackerlabs/wadl2swagger</a>><br>
<span>> Migrate WADL content to RAML<br>
> Move all API content into project repos, aggregate those into an API<br>
> reference site<br>
<br>
</span>Very nice :) Have you got as far as looking at how swagger does API<br>
versioning yet?<br>
<br>
A quick google found:<br>
<a href="http://stackoverflow.com/questions/22224308/servicestack-swagger-ui-and-api-version-number" target="_blank">http://stackoverflow.com/questions/22224308/servicestack-swagger-ui-and-api-version-number</a><br>
<br>
which looks like we'd have to spin up some different AppHosts for each<br>
API version. Shouldn't be too hard with our automation, and maybe it's<br>
improved in the intervening year.<br></blockquote></div></div></div></div></div></blockquote><div><br></div><div>Reading deeper, that's not really what we need. <span style="font-family:'Helvetica Neue',Helvetica,Arial,sans-serif;font-size:13px;line-height:16.8999996185303px">ServiceStack is a commercial, DTO-driven web services framework for .NET or Mono. We'll need an open source solution. We may need to ensure that Swagger itself is extensible enough for us to add an OpenStack release tag that we can display. I was imagining some queriable data like "since-version: diablo" or "openstack-version-available: juno, kilo, liberty" that could then be displayed or filtered upon.</span></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><div><div class="h5"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<br>
So, here's a question:<br>
<br>
Do people prefer:<br>
* A single API reference per release (eg Kilo - not api release)<br>
* A single API reference per API version that has 'available in release<br>
X' labels per API call, where methods aren't commonly available.<br>
</blockquote><div><br></div></div></div><div>I think it's this. Steve Gordon has mentioned it in the past, Steve, is this what your users would prefer?</div><span class=""><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">* Something else<br></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span><br>
> If anyone is interested, let's talk at the Summit at the API docs<br>
> session whenever that lands.<br>
> Anne<br>
><br>
><br>
> --<br>
> Anne Gentle<br>
</span>> <a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a> <mailto:<a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a>><br>
<br>
</blockquote></span></div><span class=""><font color="#888888"><br><br clear="all"><div><br></div>-- <br><div>Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</font></span></div></div>
</blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature">Anne Gentle<br><a href="mailto:annegentle@justwriteclick.com" target="_blank">annegentle@justwriteclick.com</a></div>
</div></div>