Open Stack

On Sun, Apr 26, 2015 at 8:00 PM, Anne Gentle <annegentle at justwriteclick.com>
wrote:

>
>
> 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.
>>
>
Another requirement we'll probably have is web design for this project.
Tom, can I ask you how I should request that from the Foundation?
Thanks,
Anne


> > Anne
>> >
>> >
>> > --
>> > Anne Gentle
>> > annegentle at justwriteclick.com <mailto:annegentle at justwriteclick.com>
>>
>>
>
>
> --
> Anne Gentle
> 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/51411c84/attachment.html>