16:01:08 <etoews> #startmeeting api wg
16:01:10 <openstack> Meeting started Thu May  7 16:01:08 2015 UTC and is due to finish in 60 minutes.  The chair is etoews. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:01:11 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:01:13 <openstack> The meeting name has been set to 'api_wg'
16:01:22 <elmiko> yo/
16:01:25 <vikram__> bye
16:01:27 <etoews> sound off if you're here for api wg
16:01:33 <cdent> o/
16:01:36 <alex_xu> o/
16:01:54 <stevelle> o/
16:01:55 <etoews> welcome alex_xu!
16:02:01 <alex_xu> etoews: thanks :)
16:02:46 <miguelgrinberg> hi
16:02:48 <dtroyer> o/
16:03:02 <etoews> excellent
16:03:11 <etoews> #topic agenda
16:03:18 <etoews> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
16:03:36 <etoews> #topic previous meeting action items
16:04:07 <etoews> hmmm...not the right link in the wiki. 1 sec.
16:04:43 <jaypipes> hi guys, sorry for being late.
16:04:44 <etoews> #link http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-04-30-00.01.html
16:04:50 <etoews> np
16:04:53 <sigmavirus24> jaypipes: I'm later =P
16:05:01 <jaypipes> :)
16:05:11 <etoews> i missed last week so i'm the latest there is
16:05:21 <elmiko> so, i put the evaluating api changes up as a guideline for review, #link https://review.openstack.org/#/c/180612/
16:05:30 <elmiko> getting good comments so far
16:05:49 <elmiko> that was my action item from 2 weeks ago
16:05:59 <etoews> ah
16:06:00 <elmiko> and jaypipes i responded to your comments =)
16:06:23 <etoews> i haven't had a chance to look at that one yet. thx for getting to it.
16:06:33 <elmiko> np, i hope it ends up working out
16:06:58 <krotscheck> o/
16:07:11 <annegentle> I like the move towards microversion rather than extension
16:07:29 <etoews> yep. the knives are out for extensions.
16:08:13 <elmiko> i will change the language to mention microversions instead of extensions in the next version, i wanted to leave it open for more comments before revising though.
16:08:33 <etoews> makes sense
16:08:49 <annegentle> so, I am also commenting inline, but in order to point out inadequate documentation, we need to define adequate.
16:09:02 <annegentle> I can take a stab at it if you like I have some ideas/background in this.
16:09:17 <elmiko> sure! any help would be appreciated =)
16:09:19 <annegentle> where would that "adequacy" go?
16:09:27 <annegentle> in a new guideline?
16:09:47 <etoews> "some ideas/background in this" ...snort...that's putting it mildly.
16:10:04 <annegentle> etoews: snort
16:10:09 <elmiko> hmm, would a guideline about creating documentation be appropriate? i'm not sure
16:10:25 <jaypipes> elmiko: ty sir! will respond again soon. sorry, meeting day today.
16:10:38 <elmiko> jaypipes: np, you made some great suggestions
16:10:58 <annegentle> elmiko: I should probably write "these are the current expectations for docs" in an API WG guideline
16:11:10 <elmiko> annegentle: yea, that makes sense
16:11:18 <annegentle> elmiko: ok, I'll take that on
16:12:04 <etoews> so just to be clear about it. we're saying that api docs are in scope for the api wg.
16:12:26 <elmiko> sounds like it
16:12:35 <etoews> or maybe it's recommendations about api docs are in scope?
16:12:51 <elmiko> i'm more comfortable with that statement
16:12:59 <cdent> I'd think yeah recommendations
16:13:21 <annegentle> etoews: guidelines are in scope
16:13:27 <etoews> ya. and i do think it's something we should have an opinion on.
16:13:29 <annegentle> etoews: I think. Yeah, recommendations
16:13:37 <annegentle> etoews: at least to let the WG do reviews
16:13:52 <etoews> in the current state of the art, apis and api docs are highly coupled.
16:13:56 <annegentle> etoews: and I plan to be general, not to the tool level
16:14:12 <etoews> annegentle: sgtm
16:14:16 <annegentle> etoews: cool
16:14:35 <elmiko> this could have wider impact with the whole autogen doc thingie that going on currently
16:14:53 <annegentle> elmiko: yeah it really is "while I'm workign with teams on that, might as well write guidelines"
16:15:01 <elmiko> annegentle: +1
16:15:02 <etoews> right. we'll have to feel our way through this one.
16:15:07 <annegentle> true dat
16:15:28 <annegentle> I've reached out to the Image team to see if they'd be interested in proof-of-concept. their API is still smallish
16:16:07 <annegentle> though it took 7 months to get metadata definitions documented :) https://review.openstack.org/#/c/121248/
16:16:30 <etoews> that's like overnight in openstack time
16:16:33 <annegentle> etoews: LOL
16:16:36 <elmiko> lol
16:17:14 <etoews> so we kind of veered into the next topic with these action items.
16:17:17 <etoews> #topic API Reference information
16:17:21 <annegentle> ya!
16:17:33 <annegentle> #link http://libertydesignsummit.sched.org/event/29e7d4effc10832b4d6aa50339e0c973#.VUuJ6dNViko
16:17:34 <etoews> #link https://review.openstack.org/#/c/177934/
16:17:49 <annegentle> that's the session also, didn't get that added to the agenda
16:17:54 <annegentle> (in time)
16:18:20 <annegentle> So I'm making progress and drafted again, also had a question from Celiometer dev ildiko about openstack versions v microversions
16:18:49 <annegentle> #link http://lists.openstack.org/pipermail/openstack-docs/2015-May/006560.html
16:19:14 <annegentle> So I wanted to ask here: does it make sense to "lag" the OpenStack release with Dev Guides targeted for a particular release?
16:19:21 <annegentle> As in, now we'd work on a Dev Guide for Kilo
16:19:51 <etoews> what's in scope for "dev guides"
16:20:49 <annegentle> So, the idea is to scrape code ONLY for params, errors, headers, and put that info into a Swagger 2.0 spec. Then build Dev Guides around that API ref info -- so that the experience feels like crafted docs, not roboted docs.
16:21:24 <annegentle> The vision is a nicer information experience for developer.openstack.org rather than "just" an API reference.
16:21:46 <elmiko> that sounds cool
16:21:47 <annegentle> is that amenable? I share etoews concerns about utter crappiness.
16:21:56 <annegentle> as in, any time you automate it sucks for the user.
16:22:09 <elmiko> and yeah, i think doing it for kilo makes some amount of sense
16:22:20 <annegentle> moving the reviews to the teams and hand-in-hand with WG guidelines for docs feels like it's the right direction.
16:22:42 <etoews> also relevant #link http://lists.openstack.org/pipermail/openstack-docs/2015-April/006502.html
16:22:43 <annegentle> the only part that gives me pause is that we'd be backporting strings to stable/kilo potentially... across multiple repos.
16:22:46 <elmiko> although, i also like the idea of the projects being able to autogen some part of the doc for themselves
16:22:47 <annegentle> It's scary right.
16:23:20 <annegentle> Also, check out this automation starting point
16:23:21 <annegentle> #link https://review.openstack.org/#/c/179051/
16:23:34 <annegentle> I really need eyes on that ^^ as a potential solution
16:23:46 <annegentle> for the scrape
16:23:48 <annegentle> and generate
16:25:44 <etoews> annegentle: so that patch uses some python to generate swagger from the python api source code?
16:25:44 <annegentle> heh I gave you all too much to read
16:25:48 <annegentle> etoews: yes
16:25:51 <elmiko> annegentle: i looked at that the other day, would the idea be that each project provides a function that will get called by external tools?
16:26:05 <annegentle> elmiko: possibly in oslo like we do for the configuration reference currently
16:26:16 <elmiko> annegentle: cool, that's nice
16:26:19 <cdent> There was some discussion a while ago about being able to pecan -> swagger and it faltered becasue pecan makes it rather hard
16:26:28 <annegentle> cdent: yeah
16:26:41 <annegentle> cdent: I want to say ceilometer does pecan > WADL now
16:26:45 <elmiko> cdent: i did some work on a markup package to generate swagger from pecan
16:26:45 <cdent> I think it's generally a good idea and if it drives us to use more readable frameworks then  all the better
16:27:04 <annegentle> elmiko: how'd that go? say more. :)
16:27:06 <etoews> and if this works reasonably well in nailgun (whatever that is) it could potentially be rolled out to other projects via oslo?
16:27:13 <elmiko> #link https://github.com/elmiko/pecan-swagger
16:27:19 <cdent> elmiko: yeah, I think that's what I'm remembering. You were unable to do it by inspection though, right?
16:27:27 <annegentle> etoews: maybe? Stackforge licensing doesn't exactly make it straightforward but I'm investigating
16:27:36 <elmiko> it's a poc currently, but you need to add a little markup to the controller classes to help inform the hierarchy for swagger
16:27:39 <annegentle> etoews: I need to talk to a few people
16:27:56 <annegentle> elmiko: how many projects use pecan now?
16:27:58 <elmiko> cdent: correct, pecan doesn't carry any information about the ordering of it's controllers
16:28:15 <elmiko> annegentle: not sure on exact numbers, but i know of 2
16:28:27 <annegentle> elmiko: ok, ceilometer and which?
16:28:31 <elmiko> barbican
16:28:34 <annegentle> (I have a hard stop in 2 mins)
16:28:35 <annegentle> ok
16:28:49 <annegentle> I'm really wanting to get it right for "core compute" first tbh
16:28:56 <annegentle> have to prioritize
16:29:08 <etoews> annegentle: so what are the action items here before you go?
16:29:09 <elmiko> i did a test for barbican swagger and sahara swagger in #link https://github.com/elmiko/os-swagger-docs
16:29:21 <cdent> monty posted a list of all the pecan using projects to os-dev recently
16:29:27 <annegentle> cdent: yeah
16:29:30 <etoews> same as last week. ;)
16:29:35 <annegentle> aug, sorry I have to get going :)
16:29:38 <etoews> np
16:29:41 <annegentle> thanks everyone
16:29:44 * cdent wave
16:29:45 <cdent> s
16:29:45 <annegentle> see you in Vancouver :)
16:29:48 <elmiko> annegentle: later
16:29:55 <etoews> see you
16:30:20 <etoews> #action all: comment on https://review.openstack.org/#/c/177934/
16:30:43 <etoews> #action all: comment on https://review.openstack.org/#/c/179051/
16:30:51 <etoews> i'm less sure about that one ^
16:31:19 <elmiko> i like the idea of each project having a standard entry point that some external tool can use to harvest the swagger
16:32:07 <etoews> yes. machine readable api doc would be nice.
16:32:19 <etoews> lots of good use cases for that.
16:32:22 <etoews> #topic summit sessions galore
16:32:46 <etoews> #link https://libertydesignsummit.sched.org/event/e14d84514003140fe30e984027299a44
16:32:46 <etoews> #link https://openstacksummitmay2015vancouver.sched.org/event/c61ab30c4547a6c70612017e43cd6076
16:32:46 <etoews> #link https://openstacksummitmay2015vancouver.sched.org/event/0b86e7b3b74c44705d46dc1694272d63
16:33:36 <etoews> so we hit the jackpot on summit sessions. we'll be a busy bunch. i suppose that's a good problem to have.
16:34:07 <elmiko> lol, so many sched conflicts
16:34:10 <cdent> this must be a huge convention center, lots of people have surplus sessions
16:34:17 <etoews> i'd ask that everybody make a real effort to at least get to https://libertydesignsummit.sched.org/event/e14d84514003140fe30e984027299a44
16:34:28 <etoews> that will be the most high profile session
16:35:25 <etoews> i'll do my best to do a good "where we were, where we are, and where we're going" but naturally i'll need help
16:35:35 <elmiko> nice
16:36:01 <etoews> then the other 2 sessions i see as being working sessions for us
16:36:47 <etoews> if we can actually get some work done, great. if not, that's okay too.
16:37:27 <etoews> does anybody want to highlight any other api wg related sessions at the summit?
16:37:27 <elmiko> maybe we can arg^H^H^Hdiscuss some of the open reviews ;)
16:37:40 <etoews> elmiko: exactly
16:37:46 <cdent> define: API
16:37:53 <cdent> and fight
16:37:54 <elmiko> lol
16:37:57 <etoews> :troll:
16:38:05 <cdent> :)
16:38:19 <etoews> define: pragmatic
16:38:25 <elmiko> ouch...
16:38:27 <cdent> snap!
16:38:34 <etoews> cdent: oh great. now you've got me doing it.
16:39:31 <cdent> actually you and dkranz's comments on that thread yesterday helped clarify or explain some cognitive dissonance I've been experiencing in some of my api-wg interactions
16:39:32 <etoews> miguelgrinberg and i are doing a api wg related session #link http://libertydesignsummit.sched.org/event/602a2acdca6f546cef89dc0c4356e3d8#.VUuVL9pViko
16:39:56 <etoews> cdent: say more
16:39:58 <elmiko> etoews: that one looks cool
16:40:07 <cdent> jaypipes and I have this: https://libertydesignsummit.sched.org/event/bf6f86afe58148a96ab9d1dd0d30a554
16:40:21 <elmiko> cdent: that looked nice too
16:40:24 <cdent> I'll be demo-ing gabbi which makes life easier
16:40:26 <jaypipes> which I still owe cdent slides on... coming soon! damn $work
16:40:46 <etoews> ha! i owe miguelgrinberg slides
16:41:13 <cdent> etoews: on the cognitive dissonance? I had thought that a notional API already exists sort of in the ether and we were intentionally trying to create resource oriented http apis (and guidelines for such things)
16:41:17 <miguelgrinberg> etoews: we can wing it :)
16:41:35 <cdent> the comments made it clear that at least some people have a different approach (which is expected and fine, I just hadn't crystallized the difference)
16:42:03 <etoews> cdent: ah
16:42:13 <etoews> cdent: i also really liked your response to "Changing 403 Forbidden to 400" on os-dev
16:42:35 <etoews> (╯°□°）╯︵ ┻━┻
16:42:38 <elmiko> yea, that post definitely made me more confused about which was more correct lol
16:42:44 <elmiko> etoews: yes!
16:43:05 <cdent> we looked around and it seems that 403 is common out there in web land for such things
16:43:16 <cdent> but that doesn't really address the underlying issue about dealing with ambiguity
16:43:21 <cdent> which is a _hard_ problem
16:43:29 <etoews> cdent: i know what elmiko means. the email could have used a "and i recommend X in particular"
16:43:56 <cdent> You didn't take away that I still think 403 is right?
16:44:26 <elmiko> cdent: i did. but i was starting to think 400 sounded proper, then you blew me out of the water. now i'm not sure
16:44:27 <etoews> that was my impression but it wasn't stated explicitly...or was it?
16:45:02 <etoews> let's move on in a minute
16:45:04 <elmiko> i do like the idea of being able to have better categorization using the 4XX codes
16:45:24 <elmiko> etoews: cool, i have a guideline related topic too
16:45:35 <etoews> #topic guidelines
16:45:44 <elmiko> \o/
16:46:08 <elmiko> so, woodster_ from the barbican team had brought up some questions about proper usage of POST/PUT for doing creation and updating
16:46:15 <elmiko> have we started a guideline for this yet?
16:46:19 <elmiko> also, woodster_ ^^
16:46:20 <woodster_> elmiko: ha, thanks for bring that up
16:46:28 <elmiko> ;)
16:46:46 <woodster_> I hadn't seen guidance on the proper usage of POST vs PUT
16:47:10 <cdent> this is another one of those topics with years of discussion and rules of thumb that seem to move around a lot
16:47:21 <elmiko> i thought the prevailing guidance was use POST for creation PUT for update, but apparently keystone has a situation where PUT is used for creation. (did i get that correct woodster_ ?)
16:47:22 <woodster_> I'd always thought POST was creational, and PUT was replacement. PATCH was a delta change to an existing resource
16:47:37 <etoews> right. so let's set the rule of thumb for openstack.
16:47:38 <woodster_> elmiko: that's correct
16:47:47 <elmiko> etoews: please =)
16:48:05 <cdent> the rule of thumb I use is: if you are creating and you don't know already what the resulting URI is, they you POST
16:48:09 <cdent> otherwise you PUT
16:48:28 <miguelgrinberg> +1 that's how I do it
16:48:35 <cdent> so for the vast majority of situations in openstack I would think POST for create because id's are generated on the backend
16:48:35 <elmiko> cdent: that was my thinking as well
16:48:42 <dstanek> cdent: yes
16:48:54 <etoews> ++
16:49:04 <stevelle> my rule is a little different from what cdent stated
16:49:07 <dstanek> i think the case if Keystone you are talking about we knows the uri and don't care if something is there or not
16:49:22 <cdent> wow, that was easier than expected :)
16:49:25 <stevelle> mostly the same result but different point of inflection
16:49:33 <miguelgrinberg> dstanek: that was the one that changes the password for an existing user, correct?
16:49:41 <krotscheck> Well, can I ask a followup question?
16:50:00 <etoews> of course
16:50:06 <woodster_> miguelgrinberg: I believe so
16:50:07 <dstanek> miguelgrinberg: i was thinking about some of the assignment stuff - i'd have to look at password
16:50:08 <krotscheck> So let's say you POST to create a thing, is the appropriate response either a 201, or a 300 Here's-where-the-thing-with-the-new-id is?
16:50:26 <cdent> 201 with a location header
16:50:34 <etoews> that we have a guideline for!
16:50:39 <krotscheck> Oh good!
16:50:43 * krotscheck goes away now :)
16:50:54 <elmiko> sounds like we need an action item for a POST/PUT guideline?
16:51:10 <etoews> krotscheck: #link http://specs.openstack.org/openstack/api-wg/guidelines/http.html#xx-success-codes
16:51:18 <cdent> I'll take that action if nobody else wants it
16:51:19 <miguelgrinberg> dstanek: this http://docs.openstack.org/developer/keystone/api_curl_examples.html#post-v3-users-user-id-password
16:51:35 * krotscheck thinks redirect is more "REST pure", but vastly prefers not adding additional HTTP noise.
16:51:44 <miguelgrinberg> dstanek: it's a pretty odd one, as it requires the old password, even though you must authenticate to have access
16:51:48 <elmiko> cdent: sounds good to me =)
16:51:51 <etoews> krotscheck: pragmatic :)
16:52:01 <elmiko> lol
16:52:18 <woodster_> so if the URI is known, then a PUT is a better approach?
16:52:30 <krotscheck> etoews: I've written one too many browser clients to be a purist :)
16:52:40 <stevelle> if your representation is complete and accurate, including the URI then PUT is correct
16:52:42 <etoews> #action cdent: create a POST/PUT guideline
16:52:45 <cdent> krotscheck: the problem with a redirect is that browers (inc js in browsers) will follow the redirect and the vast amount of time you dont' want to
16:52:50 <cdent> thanks etoews
16:53:17 <stevelle> any generated properties would recommend POST, not just ID
16:53:22 <dstanek> miguelgrinberg: ah yes, that's a post because we are not actually replacing a resource, but rather doing some processing
16:53:59 <etoews> cdent: i'm not sure if it's a totally new guideline and should use elmiko's template #link http://specs.openstack.org/openstack/api-wg/template.html or if it's an update to an existing page.
16:54:04 <woodster_> We have added access control lists to our entities, so we would expose a resource like this to modify the ACL (for example): /secrets/{UUID}/acl   Then it sounds like we can just PUT to that URI
16:54:17 <etoews> maybe it depends in part on how complicated/hairy it gets
16:54:25 <elmiko> woodster_: +1
16:54:37 <cdent> I'll adapt and be pragmatic etoews ;)
16:54:39 <miguelgrinberg> woodster_: you just said it, you are modifying, not creating, so PUT is right
16:54:43 <etoews> :)
16:55:01 <woodster_> nice! Thanks for the guidance then folks
16:55:43 <etoews> woodster_: thanks for reaching out to us!
16:55:56 <etoews> 5 min left
16:56:04 <alex_xu> just question, if we have sub-error-code in the future, whether the client still depend on the status code?
16:56:44 <etoews> in that case i expect the status code becomes a "top level filter" for clients
16:57:14 <miguelgrinberg> alex_xu: you would then group the sub-error codes and return them under the parent status code that makes more sense
16:57:27 <etoews> then perhaps some real action can be taken based on the sub-error-code
16:57:42 <miguelgrinberg> for example, under 400 you can have an error code for missing arg, another for invalid arg, etc.
16:57:48 <etoews> ya
16:57:54 <etoews> that's how i see it too
16:58:08 <alex_xu> ah, I see, that sounds make sense, group some process for kind of errors
16:58:18 <miguelgrinberg> right
16:58:30 <etoews> i won't be able to make it to the meeting next week
16:59:01 <alex_xu> miguelgrinberg etoews, thanks
16:59:24 <elmiko> etoews: ack, i should be around
16:59:31 <etoews> thx elmiko!
16:59:49 <elmiko> i love the api-wg after hours meetings ;)
17:00:01 <etoews> they seem very relaxed ;)
17:00:05 <elmiko> heh
17:00:19 <etoews> see some/all? of you at the summit!
17:00:19 * cdent looks at the clock
17:00:21 <etoews> #endmeeting