<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">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:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class="">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">tom@openstack.org</a><br>
</span><span class="">> <mailto:<a href="mailto:tom@openstack.org">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">tom@openstack.org</a> <mailto:<a href="mailto:tom@openstack.org">tom@openstack.org</a>><br>
</span><span class="">>     > <mailto:<a href="mailto:tom@openstack.org">tom@openstack.org</a> <mailto:<a href="mailto:tom@openstack.org">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 class="">> 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>
<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>I think it's this. Steve Gordon has mentioned it in the past, Steve, is this what your users would prefer?</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">* Something else<br></blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class=""><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">annegentle@justwriteclick.com</a> <mailto:<a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a>><br>
<br>
</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>