16:00:37 <etoews> #startmeeting api wg
16:00:38 <openstack> Meeting started Thu Jul  2 16:00:37 2015 UTC and is due to finish in 60 minutes.  The chair is etoews. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:39 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:00:41 <openstack> The meeting name has been set to 'api_wg'
16:00:45 <etoews> hi!
16:00:49 <Vikram_> bye
16:01:43 <cdent> o/
16:02:02 * etoews still updating agenda
16:02:02 <sigmavirus24> o/
16:02:03 <miguelgrinberg> hello
16:02:08 <stevelle> o/
16:02:09 <sigmavirus24> etoews: that's a pre-meeting agneda item
16:02:14 <sigmavirus24> why didn't you do it then?
16:02:15 <sigmavirus24> =P
16:02:15 <ryansb> o/
16:02:24 <etoews> jit agenda
16:02:24 <elmiko> o/
16:02:25 <ryansb> lol
16:02:40 <etoews> #topic agenda
16:02:47 <etoews> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
16:03:16 <etoews> i didn't get to all of the reviews that could be frozen.
16:03:27 <etoews> #topic previous meeting action items
16:03:40 <etoews> #link http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-06-25-00.01.html
16:04:11 <etoews> elmiko to freeze and notify about https://review.openstack.org/#/c/180094
16:04:25 <etoews> that happened right?
16:04:33 <elmiko> yes
16:04:39 <etoews> ++
16:04:49 <etoews> etoews experiment with creating a guideline status mailing list update
16:05:09 <etoews> so i didn't get to any "experimenting" but i did give it some more thought
16:05:16 <ryansb> one better, it's merged
16:06:11 <etoews> i think i'll just send out an email on a bi-weekly or monthly basis just describing what we're up to
16:06:33 <elmiko> +1
16:06:47 <cdent> that sounds about right etoews
16:06:52 <cdent> people like the human touch
16:07:03 <elmiko> so, we are saying no to an indie 'zine that gets published during summit? ;)
16:07:21 <etoews> i'm not not saying no
16:07:27 <elmiko> lol
16:07:36 * elmiko puts away mimeograph machine
16:07:48 <ryansb> that's not right out, but I think email publishing costs are lower than indie 'zines
16:07:56 <elmiko> fair
16:08:19 <etoews> i was thinking about trying to put together a gerrit dashboard to include in the email but haven't had time to look into it
16:08:22 <etoews> #link http://ghostcloud.net/openstack_gerrit_dashboards/
16:08:54 <etoews> #link https://github.com/stackforge/gerrit-dash-creator/
16:09:10 <elmiko> that sounds kinda cool
16:09:21 <ryansb> good idea, I did that for heat a while ago
16:09:35 <ryansb> and it seemed to be used by >0 people on the team
16:09:46 <etoews> it would be nice to "encode" as much of our merge process into the dashboard
16:09:54 <ryansb> though please shorten the URL before distributing the link
16:10:14 <etoews> ya. some of the links it produces are pretty gnarly
16:10:35 <ryansb> I think heat's dash is 2K
16:10:41 <ryansb> the URL...
16:10:43 <etoews> it basically looks like an sql injection attack
16:11:20 <etoews> anyway, no idea when i'd be able to get to that.
16:11:47 <elmiko> fwiw, it sounds really nice
16:12:11 <etoews> ryansb: i might ping you about it if i run into any issues
16:12:32 <etoews> #topic ongoing reviews of API impacting code/spec
16:12:56 <ryansb> kk, here's what the heatdash looks like http://supb.ro/heatdash
16:13:06 <etoews> so this is the kind of thing i'd like to include in the newsletter
16:13:56 <etoews> a list of the ongoing reviews of API impacting code/spec
16:14:13 <etoews> the only one i'm currently aware of is the glance artifacts api spec
16:14:32 <etoews> what else is out there that people are reviewing?
16:15:07 <elmiko> we've had a minor one in sahara, but it wasn't large enough to pull in others
16:15:17 <elmiko> also, it touched on the old /task endpoint debate ;)
16:15:27 <etoews> link?
16:15:52 <etoews> i'm looking for anything within the past month btw
16:16:00 <etoews> doesn't have to be currently under review
16:16:29 <elmiko> sec
16:17:23 <elmiko> oh, heh, he forgot to mark it as APIImpact...
16:17:33 <elmiko> #link https://review.openstack.org/#/c/188011/
16:17:45 <elmiko> and i forgot to remind him...
16:17:55 <etoews> thx
16:18:35 <etoews> anyone else?
16:18:49 <etoews> it would be nice to have at least one more example ;)
16:19:55 <ryansb> *crickets*
16:20:01 <cdent> we all seem a bit tired today
16:20:06 <etoews> there must be something in nova. /ping alex_xu
16:20:43 <etoews> oh well
16:21:01 <etoews> #topic guidelines
16:21:10 <etoews> #link https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
16:21:31 <elmiko> i could really use more eyeballs on #link https://review.openstack.org/#/c/183698/
16:21:34 <elmiko> =)
16:21:57 <etoews> let's have a look
16:23:53 <etoews> "In these cases though, the implementor should exercise caution to only return these codes in situations where an error cannot be handled by the server."
16:23:56 <miguelgrinberg> I really don't have enough justification to -1, but I think text treats things as black or white, ignoring the frequently occurring gray zones
16:24:17 <etoews> do you mean "...handled by the application code." ?
16:24:45 <cdent> miguelgrinberg: isn't that rather the point: the guidelines need to paint a black and white picture so that the grey zones are tiny
16:24:55 <etoews> cdent: ++
16:25:05 <elmiko> etoews: yea, that might be a better way to word it
16:25:11 <miguelgrinberg> yeah well, I think the gray zones are there regardless of what the guidelines say
16:25:22 <etoews> miguelgrinberg: what gray zones did you have in mind in this case?
16:25:34 <elmiko> miguelgrinberg: i added the second paragraph to help address the grey zones
16:25:45 <etoews> we are the beacon of light that leads developers out of gray zones
16:25:48 <miguelgrinberg> well, I think making a distinction between server and app is really not that interesting when you look at things from the client side
16:26:21 <miguelgrinberg> from the client it's just a server, who cares if the 5xx codes are generated by the app or the server proper
16:26:39 <cdent> we are not writing guidelines for the client side miguelgrinberg, we're writing guidelines for people developing api services
16:26:44 <miguelgrinberg> catching exceptions and replacing them with a 500 is a good example of this
16:26:53 <etoews> but our audience is primarily the openstack contributors developing those servers
16:26:54 <cdent> (sorry, I got to dash away for about 5 minutes, brb)
16:27:36 <ryansb> to be fair, those same folks also write clients
16:27:37 <miguelgrinberg> What I mean is that I consider the app part of the server, because all that matters is how the client uses these responses
16:29:05 <etoews> right. but 5xx says that things are screwed up beyond the app code ability to deal with them.
16:29:06 <elmiko> i think it does make a difference on the server side when you think about 500/501 vs 502/503/504/505 though
16:29:44 <etoews> if i'm writing a client, i know that 5xx probably isn't recoverable in the near term
16:30:12 <etoews> so giving guidance to openstack contributors on it is valuable imo
16:30:13 <miguelgrinberg> etoews: right, that's the scope of the 500x, saying that they come from the server and not the app does not really help much
16:31:00 <elmiko> imo, these 5xx guidelines are more oriented at server side development
16:31:01 <cdent> the implication miguelgrinberg is that application code should not raise MyFiveHundredException('whoops')
16:31:09 <miguelgrinberg> you can say that "normally these errors are generated by the WSGI layer" or something to that effect, but it isn't black and white
16:31:10 <cdent> only the server should explicitly do that kind of thing
16:31:44 <miguelgrinberg> but there is one clear case we all agree on where a 500 is appropriate (exceptions that are unhandled)
16:31:48 <miguelgrinberg> so that breaks your rule
16:32:38 <elmiko> thats also why i said *should not* instead of *must not*
16:32:51 <elmiko> and then added the example of when you might generate them
16:33:09 <ryansb> yeah, but unhandled exceptions are (to an extent) implicit, since you needn't go out of your way to *not* handle them
16:34:02 <miguelgrinberg> well, but I could see a case where application code may end up all confused and throw a 500 to get out of a mess. Why not?
16:34:15 <miguelgrinberg> That's what the 500 is about
16:34:24 <elmiko> ok, so the main point of this guideline was to add something for developers creating server-side apps. does it seem appropriate for that type of guidance?
16:34:29 <miguelgrinberg> it does not need to be just for unhandled exceptions
16:35:05 <elmiko> agreed miguelgrinberg, that's why i added the example of when you might raise a 500
16:35:27 <elmiko> i just wanted to signal that "hey, you might need to do this and that's acceptable"
16:35:40 <etoews> i think it's appropriate. it strongly discourages dev from throwing a 5xx.
16:35:49 <cdent> you raise a 500 when you catch an unhandled exception, but your app has unhandled exceptions _regularly_ it is broken and should be handling those exceptions more defensively
16:35:50 <elmiko> right, unless you have a good reason
16:36:04 <cdent> if it can defend against them, then it can also turn them into 4xx
16:36:11 <elmiko> cdent: agreed
16:36:25 <miguelgrinberg> cdent: not always
16:36:43 <miguelgrinberg> I disagree with the idea of the 400 being a catch-all for app errors for example
16:36:46 <cdent> You'll need to convince me miguelgrinberg because you just saying "not always" isn't really getting anywhere
16:37:43 <etoews> "throwing a 500 to get out of a mess" concerns me. 500 is not a get out of jail free card.
16:37:44 <miguelgrinberg> 5xx are for server errors and 4xx are for user errors, you have to return the ones that makes sense, who generates what does not matter
16:38:24 <etoews> to me the flow would be like this
16:38:24 <miguelgrinberg> etoews: I think it is. If there is a bug in the code, and that takes you to a place you shouldn't be, I think 500 makes sense
16:38:27 <cdent> sure miguelgrinberg: the point I'm trying to make is that server errors should be minimized, by being defensive, and if you can be defensive you can almost always define the error as a 4xx
16:38:46 <cdent> so if you _cannot defend_ then a 500 makes sense
16:39:04 <cdent> but that should be vanishingly rare (in the ideal case)
16:39:20 <cdent> and the guidelines should be representing the idealized aspirational case
16:39:30 <etoews> the code has a bug and does handle it, it throws a 500 but this is a **temporary** situation.
16:39:53 <etoews> the code gets fixed, deployed, and that 500 goes away.
16:39:54 <miguelgrinberg> temporary until you upgrade
16:39:59 <etoews> ++
16:40:27 <miguelgrinberg> that's still the intended use for a 500
16:40:35 <etoews> and that's fine
16:40:45 <etoews> i just prefer to strongly discourage using 500 as an out
16:40:52 <etoews> devs **will** abuse it
16:41:03 <cdent> etoews++
16:41:36 <etoews> it's natural that 500s happen from time to time because bugs but let's not encourage their use
16:41:37 <elmiko> etoews: +1
16:42:30 <elmiko> i'm gonna make the change etoews suggested, but then could we continue the argument on the review?
16:42:38 <cdent> elmiko++
16:42:42 <miguelgrinberg> yep
16:42:44 <etoews> elmiko: good point.
16:42:46 <elmiko> (i'm slightly confused about how to improve the language in the guideline)
16:42:57 <elmiko> thanks everybody!
16:43:08 <stevelle> do we need a recommendation that says "fix your bugs?" :)
16:43:24 <miguelgrinberg> I prefer "do not write bugs in your app"
16:43:29 * cdent sighs
16:43:39 <elmiko> lol
16:43:58 <elmiko> stevelle: that should be the only guideline ;)
16:44:22 <etoews> yep. just add that guideline and our work here is done.
16:44:23 <stevelle> great, we adjourn for lemonade then?
16:44:43 <etoews> a spot of tea
16:44:52 <ryansb> now that you finished all the guidelines, sure
16:45:03 <etoews> #topic freezing
16:45:16 <etoews> lots of guidelines ready for freeze
16:45:26 <etoews> the list on the agenda isn't even complete.
16:45:29 <elmiko> \o/
16:46:38 <etoews> i've been adding CPL reviewers with this script. https://review.openstack.org/#/c/193753/1/tools/add-reviewers.py
16:47:17 <etoews> Salvatore Orlando had a question about doing this with a gerrit group instead
16:47:32 <etoews> iirc i think someone explored that
16:47:48 <etoews> but i may not recall correctly
16:47:56 <etoews> does that ring any bells for anyone?
16:47:57 <cdent> how easy is it to manage those groups
16:48:23 <etoews> i think you need gerrit admin so not easy at all
16:48:34 <ryansb> probably harder than updating a json file
16:48:43 <etoews> my thoughts too
16:48:45 <cdent> thus my question
16:49:06 <etoews> alright. i think i'll just go forward with the script then.
16:49:43 <ryansb> +1
16:49:54 <etoews> elmiko: anything you want to discuss on re-review?
16:50:13 <elmiko> not specifically, just that we need to be dilligent about getting those back out the door =)
16:50:34 <etoews> ++
16:50:34 <elmiko> they have been sitting for awhile after being reviewed by the larger openstack group
16:50:43 <etoews> #topic APIImpact
16:50:55 <etoews> #link https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z
16:52:08 <etoews> what's going on here? #link https://review.openstack.org/#/c/147738/
16:53:09 <cdent> that's a rather interesting sample url
16:53:14 <ryansb> There's #link https://review.openstack.org/#/c/188364/7 that's about adding an API for describing supported heat functions
16:53:37 * cdent needs to eke out more time for this aspect of the work
16:53:54 <etoews> cdent: looks nothing like we have in http://specs.openstack.org/openstack/api-wg/guidelines/pagination_filter_sort.html#filtering
16:54:51 <cdent> indeed
16:55:41 <elmiko> its an interesting use though, how would we recommend specifying something like the glance metadata as filter options?
16:56:26 <ryansb> 4 minute warning
16:56:35 <cdent> I'm not sure if we want to use ceilometer as an exemplar but the way it tends to refer to metadata keys is metdata.<some key>
16:56:40 <cdent> and things of that ilk
16:56:57 <cdent> so using '.' as a descent indicator
16:57:12 <elmiko> ah, so in this case, /volumes/details?glance_metadata.image_name=xxx ?
16:57:27 <cdent> yeah, but then you've got problems with things named image.name
16:57:33 <elmiko> right
16:57:37 <cdent> so it just moves the worms around
16:57:43 <elmiko> interesting question though
17:00:29 <etoews> well comment on the review if you have time/energy.
17:00:40 <etoews> #endmeeting