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.
>>
>
Reading deeper, that's not really what we need. 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.


>
>> 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.
>> > 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/59dcf57b/attachment.html>