16:00:30 <etoews> #startmeeting api wg
16:00:36 <openstack> Meeting started Thu Dec 18 16:00:30 2014 UTC and is due to finish in 60 minutes.  The chair is etoews. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:37 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:00:39 <openstack> The meeting name has been set to 'api_wg'
16:00:42 <dtroyer> o/
16:00:47 <isviridov_away> o/
16:00:52 <elmiko> \o/
16:00:55 <sigmavirus24> o/
16:00:57 <stevelle> o/
16:01:06 <etoews> seasons greetings :)
16:01:30 <etoews> #topic agenda
16:01:33 <sigmavirus24> I season my greetings lightly but that's personal taste
16:01:39 <etoews> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
16:01:40 <elmiko> lol
16:02:09 <etoews> #topic api definition formats
16:02:27 <elmiko> swagger go-go
16:02:29 <etoews> elmiko: was it you that brought this up at the end of the last meeting?
16:02:32 <elmiko> yea
16:02:40 <etoews> swagger a go-go
16:02:50 <elmiko> mainly in the guise of creating a swagger generator for sahara
16:03:01 <etoews> guises are good
16:03:09 <etoews> can you share that link again?
16:03:10 <elmiko> the larger effort i was getting at was trying to generate something for the api-ref website
16:03:22 <etoews> that is a larger effort
16:03:25 <etoews> but worthwhile
16:03:29 <elmiko> #link https://github.com/elmiko/sahara-doc
16:03:46 <elmiko> it's pretty basic so far, but generates the minimum required doc for swagger2.0
16:04:08 <etoews> do you have the generated doc somewhere?
16:04:19 <elmiko> 1sec, i can make one
16:04:35 <etoews> sure then gist or paste or whatever
16:04:52 <etoews> so let's discuss the more general issue
16:05:06 <elmiko> http://paste.openstack.org/show/152783/
16:05:40 <etoews> i'm totally in favour of having api definition formats a thing that the api wg advocates for. that is to say, i think it's in scope for us. thoughts?
16:05:56 <dtroyer> ++
16:05:56 <elmiko> total agreement from me
16:06:06 <stevelle> yes please
16:06:14 <sigmavirus24> etoews: agreed
16:06:29 <ryansb> ++
16:06:44 <etoews> alright. i need to update the scope section of the wiki page anyway.
16:07:05 <etoews> #action etoews update the scope section of the wiki page and include api definition format
16:07:46 <etoews> at the moment i'm totally undecided on which one we should recommend or even if we should recommend one.
16:08:14 <elmiko> if we are going to have them all on api-ref we need to at least provide a set of formats that are acceptable
16:08:26 <etoews> is it better to just say we recommend an api def format, here are some examples.
16:08:39 <elmiko> wadl is ok, if you like xml. but i'm finding swagger pretty easy to work with.
16:08:54 <etoews> so here's another thing
16:09:01 <elmiko> also it has some nice overlap with jsonschema stuff
16:09:13 <isviridov> Is swagger integrated with sphinx somehow?
16:09:26 <isviridov> Or any other tool>
16:09:26 <elmiko> isviridov: that's a good question
16:09:34 <etoews> one of the reasons i think wadl wasn't as useful as it could have been was because it was used as a documentation format.
16:09:52 <etoews> we don't need documentation. we need definition.
16:10:03 <etoews> we need the projects to own these definition files.
16:10:19 <etoews> the defs should be the contract between client and server
16:10:33 <isviridov> but it would be great to generate some documentation from definition in already adopted format. I mean sphinx
16:10:45 <elmiko> isviridov: +1
16:11:24 <etoews> so rather than having api-ref be the place where these defs live
16:11:34 <sigmavirus24> I worked on a ruby project that used json schema to enforce a contract on a live server between client and server code
16:11:35 <etoews> the defs live in the individual projects
16:11:51 <etoews> and api-ref makes use of them
16:11:53 <elmiko> etoews: would the idea be that api-ref would pull from the projects?
16:12:00 <sigmavirus24> I have a case-study up that we can look to as a reference for architecture if we're interested in something like that
16:12:04 <etoews> elmiko: something like that
16:12:15 <elmiko> sigmavirus24: post a link!
16:12:22 <etoews> sigmavirus24: yes. that's the direction we need to go.
16:12:29 <sigmavirus24> #link https://github.com/bendyworks/caravan
16:12:41 <sigmavirus24> I had thought of doing a case-study app with flask for simplicity but never got around to it
16:12:41 <etoews> otherwise it's just another doc format that lags behind what the def actually is
16:12:54 <sigmavirus24> I let my former employer publish it a few weeks ago for reasons like this :P
16:12:58 <stevelle> isviridov: do you have much familiarity with swagger?
16:13:08 <isviridov> stevelle not yet
16:13:26 <elmiko> #link https://github.com/swagger-api
16:13:28 <elmiko> fyi
16:13:36 <etoews> i talked to the barbican folks about adopting a model like this. api def first dev.
16:13:41 <etoews> they were open to the idea
16:13:48 <isviridov> elmiko thx
16:13:49 <stevelle> isviridov: swagger has tools to publish good human-readable documentation
16:13:50 <etoews> but didn't have dev time to commit to it
16:14:16 <isviridov> stevelle I see
16:14:45 <etoews> if we could help projects bootstrap their api def efforts, that might be one way to make it stick.
16:15:15 <etoews> we would also want to demonstrate the benefits the project gained from adopting an api def
16:15:53 <sigmavirus24> one thing i should mention is that this ruby project also used the API definition files to test/build clients and would probably be awesome to have something similar for openstack APIs
16:16:22 <etoews> sigmavirus24: you're reading my mind
16:16:42 <etoews> does anybody have the time to create a swagger def for barbican?
16:17:02 <etoews> i wouldn't have time for it until next year but am willing to do it
16:17:07 <elmiko> etoews: i've been looking into barb, i could take a pass at it
16:17:42 <etoews> elmiko: have you seen the barb api "docs"
16:17:49 <elmiko> etoews: yes
16:17:59 <sigmavirus24> etoews: "docs"
16:18:02 <sigmavirus24> lol
16:18:05 <elmiko> etoews: i might go through their pecan impl to pull out the swagger spec though
16:18:14 <etoews> some wiki page somewhere.
16:18:20 <etoews> _goes off to find link_
16:18:28 <elmiko> i believe it's still under the cloudkeep stuff
16:18:50 <etoews> #link https://github.com/cloudkeep/barbican/wiki/Application-Programming-Interface
16:19:05 <etoews> the "docs" aren't sooooo bad :)
16:19:19 <etoews> there are worse
16:19:23 <sigmavirus24> oh etoews the other thing is that this format allowed for microversioning
16:19:25 <elmiko> their definitely workable, but non-ideal
16:19:47 <etoews> sigmavirus24: "this format" == ??
16:19:59 <sigmavirus24> *the ruby project I referenced earlier
16:21:03 <etoews> sigmavirus24: which is the api def format file in that project?
16:21:24 * sigmavirus24 goes to get a link
16:21:38 <elmiko> etoews: if i generate something for barb, should i just toss it on github?
16:21:44 <sigmavirus24> https://github.com/bendyworks/caravan/blob/master/lib/endpoint_definitions/users/user.yml etoews
16:22:06 <sigmavirus24> given how sinatra/rack work, the params in the URL are also documented in teh format so it's not just request/response body
16:22:30 <etoews> elmiko: yes. at that point we can take it to the ml and see what barbican thinks.
16:22:36 <elmiko> etoews: cool
16:23:12 <etoews> #action elmiko to generate swagger doc for barbican and commit to github somewhere
16:23:58 <etoews> sigmavirus24: i that it that's a format defined by the framework?
16:24:18 <sigmavirus24> etoews: interpol is the library there
16:24:21 <sigmavirus24> we don't have to follow it to the T
16:24:29 <sigmavirus24> but interpol is just using jsonschema under the covers
16:24:31 <etoews> "Interpol is an open source toolkit for policing your HTTP JSON interface maintained by Moz. It uses YAML files with definitions of the expected request and the promised response. These are called endpoint definitions. Caravan uses Interpol to enforce a contract with the consumer of the JSON interface."
16:24:44 <etoews> #link https://github.com/bendyworks/caravan#interpol-endpoint-validation
16:24:50 <etoews> interesting.
16:25:18 <etoews> i think we'd want to go with a more broadly known/accepted format moving forward though
16:25:22 <sigmavirus24> yeah
16:25:31 <sigmavirus24> but the behaviour is what I care about personally
16:25:36 <etoews> right
16:25:43 <sigmavirus24> it's just a concrete example
16:25:49 <etoews> i particularly like "policing your HTTP JSON interface"
16:25:59 <sigmavirus24> It's a strategy used by moz.com and it works really reallly well for them
16:26:11 <etoews> such things require much policing
16:26:16 <sigmavirus24> I'm not sure how much of their architecture I can talk about though =P
16:26:41 <etoews> understood. thanks for the concrete example though.
16:26:51 <sigmavirus24> you're quite welcome
16:27:15 <etoews> what actually might be really helpful is if you could elaborate on the real benefits moz saw from adopting an api def.
16:27:35 <etoews> we should discuss this on the ml
16:27:39 <sigmavirus24> I'll write up a document to that effect
16:27:43 <etoews> more viz
16:27:44 <sigmavirus24> Action item forme?
16:27:48 <elmiko> i think another question about these generated formats is how much do we want to talk about generating the base reference, and then hand tailoring with custom info(e.g. descriptions)?
16:27:52 <sigmavirus24> s/forme/for me/
16:28:19 <etoews> sigmavirus24: as in starting the discussion on the ml or just documenting benefits.
16:28:33 <etoews> hmmmm...the benefits could be a reply to the discussion
16:29:10 <etoews> elmiko: that's a good point. i'm not sure.
16:29:31 <elmiko> my understanding is that the wadl present on api-ref is a mix of auto-generate and handhack
16:29:32 <etoews> if these formats are maintained by the projects themselves, it might be too much of a burden for them.
16:29:40 <sigmavirus24> etoews: roger that
16:30:01 <etoews> at least initially.
16:30:33 <etoews> sigmavirus24: okay. i'll kick off a discussion and if you could reply with the benefits that would be really helpful.
16:30:39 <elmiko> etoews: would be awesome to see some sort of oslo package that could help with the generation
16:30:44 <sigmavirus24> etoews: will do
16:30:56 <etoews> #action etoews start discussion about api def formats on ml
16:31:25 <etoews> #action sigmavirus24 reply to discussion with benefits moz saw from using an api def format
16:31:45 <etoews> elmiko: i hadn't considered that. that could work.
16:32:11 <elmiko> i'm just thinking about how we could create something that would help the projects maintain their refs
16:32:29 <etoews> elmiko: are you thinking generate the api def formats from the code using an oslo package?
16:32:44 <elmiko> etoews: not completely, but something to help.
16:32:54 <stevelle> many frameworks have decorators or the like to help with generating swagger docs.
16:32:58 <elmiko> we have enough different wsgi impls that we probably can't have a single package to generate
16:33:03 <stevelle> pecan doesn't, though
16:33:13 <elmiko> stevelle: yea... =(
16:33:26 <elmiko> nice thing about swagger though, is that json is easy to generate from python
16:33:56 <etoews> this is all good fodder for a discussion on the ml
16:34:03 <elmiko> etoews: agreed
16:34:07 <etoews> we should move on
16:34:46 <etoews> #topic previous meeting action items
16:34:53 <etoews> #link http://eavesdrop.openstack.org/meetings/api_wg/2014/api_wg.2014-12-11-00.00.html
16:35:26 <etoews> hmmmm...i don't think miguelgrinberg or ycombinator are around
16:36:05 <sigmavirus24> miguelgrinberg: might show up late
16:36:12 <sigmavirus24> but he may also just not show up
16:37:24 <etoews> gotcha. i do see he started a metadata guideline.
16:37:26 <etoews> #link https://review.openstack.org/#/c/141229/
16:37:50 <etoews> so something i think we need to start doing more of is this.
16:38:39 <etoews> #1 under #link https://wiki.openstack.org/wiki/API_Working_Group#Deliverables
16:38:58 <etoews> analyze current design
16:39:19 <sigmavirus24> yep
16:39:39 <etoews> i don't want the wg to act like we're creating guidelines in a vacuum.
16:39:44 <stevelle> there was another review I looked at yesterday, on addressing collections, that also did that.
16:39:52 <etoews> yep.
16:39:57 <elmiko> etoews: +1
16:40:35 <etoews> okay. i'm going to make a point about that on the ml.
16:40:55 <etoews> i have a feeling like it might uncover some gremlins
16:41:48 <etoews> are we striving for a good enough design that's consistent or are we striving for an ideal like hateoas?
16:41:57 <etoews> *ducks*
16:42:03 <sigmavirus24> etoews: why not both?
16:42:03 <sigmavirus24> =P
16:42:04 <elmiko> lol
16:42:08 <annegent_> pragmatic
16:42:29 <sigmavirus24> pragmatic with a hint of idealism is what I've been thinking of personally
16:42:42 <etoews> anyway, i just suspect that might fall out of such a discussion.
16:42:53 <etoews> i might be over thinking it though.
16:43:10 <elmiko> sigmavirus24: +1
16:43:26 <etoews> #action etoews start discussion on ml about doing more analysis of current design and not creating guidelines in a vacuum
16:43:35 <annegent_> a light scent of idealism should be detected :)
16:43:52 <annegent_> +1 for more analysis of current state
16:44:18 <etoews> annegent_ has joined the game
16:44:40 <annegent_> put me in, coach!
16:44:43 <etoews> back on prev action items.
16:45:17 <etoews> i pinged jaypipes about merging some of the guidelines. he merged the infra ones and commented on others.
16:45:58 <etoews> not much time left.
16:46:01 <etoews> #topic APIImpact
16:46:06 <etoews> #link https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z
16:46:18 <etoews> blerg. anything we can discuss in 5 min?
16:47:01 <sigmavirus24> https://review.openstack.org/139775 should be simple enough
16:47:05 <sigmavirus24> also it's mine =P
16:47:26 <etoews> that's fair. :)
16:47:46 <sigmavirus24> glance supports downloading images in chunks (only when using the filesystem as a store) but doesn't return 206 when it responds properly. the problem is that every other storage device doesn't respect it
16:48:15 <sigmavirus24> so it needs to change so that it returns the proper status code but can also simultaneously support the operation properly so there are some changes in the pipeline for that
16:49:08 <sigmavirus24> It has APIImpact in the sense we're changing status codes midstream and I'm not convinced it's a good idea even if it's the right thing =P
16:49:57 <annegent_> I think our guidance generally was the guidelines can be applied to current API definitions but are meant for future designs.
16:50:31 <etoews> from the patches i can't tell what the status code was originally
16:50:36 <sigmavirus24> 200
16:50:55 <sigmavirus24> Which is correct when downloading the entire image at once
16:51:11 <etoews> is that even remotely practical?
16:51:22 <etoews> (download the entire image at once)
16:51:25 <sigmavirus24> ¯\_(ツ)_/¯
16:51:55 <ryansb> on 10G sure
16:52:04 <elmiko> lol
16:52:06 <etoews> ha
16:52:11 <sigmavirus24> this is probably off-topic at this moment
16:52:26 <etoews> i don't think so
16:52:49 <etoews> a 206 seems perfectly reasonable
16:52:53 <ryansb> I mean, an 8gb image would take around 8 seconds on a 10gigabit link
16:52:56 <etoews> or necessary really
16:53:30 <etoews> ryansb: assuming the network is reliable. ;)
16:53:31 <sigmavirus24> etoews: yeah.
16:53:46 <sigmavirus24> I meant the practicality of downloading the entire image is probably out of scope for discussion
16:53:59 <etoews> ah yes. my tangent.
16:54:04 <etoews> oops
16:54:20 <sigmavirus24> but yeah, this makes me wonder if we should be defining all status codes (like usage of 206) in the WG too
16:54:28 <sigmavirus24> we've had enough yaks shaved over 201/204 on creation and such
16:54:36 <etoews> i think so
16:55:08 <etoews> if there had been a guideline for something like this in the first place the proper status code might have even gotten used!
16:55:25 <sigmavirus24> heh
16:55:34 <sigmavirus24> there is a guideline... it's RFC 7233
16:55:36 <sigmavirus24> =P
16:55:53 <dtroyer> even in the case of the 201/204 discussion, we should document that even if no clear reccommendation is made to attempt to at least short-circuit the next time that discussion arises
16:56:02 <etoews> 5 min left. i think we'll have to skip the guidelines topic.
16:56:06 <elmiko> dtroyer: +1
16:56:10 <etoews> dtroyer: +1
16:56:35 <etoews> we can also think of the guidelines as providing mental heuristics for others.
16:56:39 <elmiko> it's tough work, especially getting a consensus, but very valuable to at least have a guide for response codes
16:56:50 <etoews> #topic open topics
16:57:16 <etoews> i'm assuming we're canceling next week's meeting. ;)
16:57:31 <elmiko> makes sense
16:57:32 <stevelle> +1 that
16:57:32 <etoews> should probably cancel the week after too.
16:57:50 <annegent_> yeah
16:58:08 <etoews> so cancel dec. 24 and jan. 1.
16:58:34 <etoews> anything else anybody wants to fire off in 2 min or less?
16:58:48 <elmiko> happy holidays?
16:59:00 <etoews> happy holidays
16:59:04 <elmiko> +1
16:59:04 <sigmavirus24> enjoy the two week break?
16:59:08 <etoews> (note the lack of question mark)
16:59:18 <elmiko> that's why i plus oned ;)
16:59:28 <etoews> :D
16:59:46 <etoews> awesome. thanks everyone!
16:59:58 <ryansb> cheers!
17:00:05 <sigmavirus24> thanks etoews
17:00:15 <etoews> cheers!
17:00:17 <elmiko> have fun all!
17:00:17 <etoews> #endmeeting