<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Sun, Apr 26, 2015 at 7:32 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 class="">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><br>
</span><span class="">> <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>
</span>Of course - this is just an attempt to start the brainstorming, not fix<br>
the specific patch :)<br>
<br>
<br></blockquote><div><br></div><div>Absolutely! </div><div><br></div><div>Ideas I'd like to poke at:</div><div>Migrate WADL content to Swagger, please look at WADL2Swagger <a href="http://github.com/rackerlabs/wadl2swagger">github.com/rackerlabs/wadl2swagger</a></div><div>Migrate WADL content to RAML</div></div>Move all API content into project repos, aggregate those into an API reference site</div><div class="gmail_extra"><br></div><div class="gmail_extra">If anyone is interested, let's talk at the Summit at the API docs session whenever that lands.</div><div class="gmail_extra">Anne<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>