16:00:45 <cdent> #startmeeting api-wg
16:00:46 <openstack> Meeting started Thu Oct 13 16:00:45 2016 UTC and is due to finish in 60 minutes.  The chair is cdent. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:47 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:00:50 <openstack> The meeting name has been set to 'api_wg'
16:00:54 <cdent> #chair etoews elmiko
16:00:54 <openstack> Current chairs: cdent elmiko etoews
16:00:57 <edleafe> \o
16:00:57 <elmiko> hi
16:01:01 <ediardo> o/
16:01:05 <etoews> \o
16:01:05 <cdent> #link agenda: https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
16:01:06 <jlopezgu> o/
16:01:18 <etoews> wow. big crowd.
16:01:42 <elmiko> seriously =)
16:01:46 <edleafe> I understood that there would be punch and pie
16:01:52 <elmiko> hehe
16:01:58 <cdent> just as a point of order before we get rolling, I'm pretty heavily invested in at least one of these agenda items, so I'd like to recuse myself from writing the newsletter this time. otherwise i'm likely to over-editorialize
16:02:11 <elmiko> ack
16:02:34 <elmiko> you have got me curious what all the hub-bub is about
16:02:41 <cdent> that out of the way:
16:02:49 <cdent> #topic action items from last meeting
16:03:16 <cdent> I was going to follow up on the bof at summit. I found it, i was just never informed that it was accepted
16:03:46 <cdent> #link https://www.openstack.org/summit/barcelona-2016/summit-schedule/events/16817/api-working-group-meetup
16:04:30 <cdent> that moves us directly into the first topic on open mic
16:04:33 <cdent> #topic open mic
16:04:38 <cdent> which is summit update
16:05:16 <cdent> I had been under the impression that the idea for there being api usability tests at the summit had died down, but that's not the case, it was another communication drop
16:05:34 <cdent> There will be api related tests monday morning. When I'm not there.
16:05:35 <elmiko> api usability tests?
16:05:49 <cdent> yeah, I'm not sure how that works either, but that's part of the plan
16:05:52 * cdent locates links
16:05:55 <elmiko> interesting
16:06:08 <cdent> #link
16:06:12 <cdent> #undo
16:06:12 <openstack> Removing item from minutes: <ircmeeting.items.Link object at 0x7fd8b5f49490>
16:06:20 <cdent> #link api usability: https://wiki.openstack.org/wiki/UX#Participate_in_a_usability_study_being_conducted_at_the_Barcelona_Summit.21
16:06:51 * elmiko looks
16:07:07 <cdent> There's been a lack of written information so it has failed to progress with any real substance, as of yet
16:07:22 <elmiko> sounds cool, i'm surprised there hasn't been more noise of collaboration with us
16:07:34 <etoews> there was an email thread...
16:07:34 <edleafe> yeah, didn't see anything about APIs there
16:07:43 <elmiko> etoews: ahh, gotcha. thanks
16:08:02 <cdent> elmiko: I've made several efforts with the organizers to get them to send more email about it
16:08:04 <cdent> over and over
16:08:08 <cdent> and failed every single time
16:08:24 <elmiko> that's a bummer
16:08:29 <etoews> #link https://etherpad.openstack.org/p/osux-api-oct2016
16:09:00 <cdent> both in the sense of "send email to the list" and "send me email about this, if you can't do that, because I can't schedule a webex with my current schedule, but would love to talk more"
16:09:03 <elmiko> oh yeah, this does job my memory
16:09:21 <elmiko> s/job/jog/
16:10:12 <cdent> I have response pending to again redirect to the public list, at which point I think we have to say "we tried"
16:10:14 <etoews> dimes to dollars sez all of the feedback will be about the documentation (which is fair) and not about the actual api (which is unfortunate)
16:10:51 <elmiko> that seems highly likely etoews
16:11:16 <edleafe> etoews: yup
16:12:05 <cdent> the orchestrator is piet kruithof at intel, if anyone has contact with him, there's probably an opportunity to help shape things
16:12:43 <cdent> shall we move on?
16:12:48 <etoews> piet_: ^^
16:13:10 <piet_> etoews Hiya
16:13:47 <piet_> Ohhhh API folks? Want to chat about the study?
16:14:06 <etoews> piet_: have you read the scrollback?
16:15:05 <piet_> Just got out of another meeting
16:16:09 <piet_> Reading now
16:16:28 <cdent> can we return to this at the end if there is time? I'd like to make sure we take advantage of ediardo while he's here (and vice versa)
16:16:36 <etoews> cdent: yep. let's move on.
16:16:39 <piet_> Sure
16:16:57 <ediardo> hi
16:17:07 <cdent> so next topic is that ediardo has some ideas that might be useful for enhancing the links in errors response
16:17:16 * ediardo grabs the mic
16:17:23 <cdent> #link error knowledge base proposal: https://docs.google.com/document/d/1fdRuPsIenaulxjXGgEK35UeWORiwOPpdX7OxL6E-ICw/edit
16:17:31 * cdent cedes the floor
16:17:56 <ediardo> Eddie Ramirez here, working at intel. There's this tiny demo we did and we believe you folks should see it :)
16:18:08 <ediardo> #link same doc but on etherpad https://etherpad.openstack.org/p/api-error-messages ;)
16:18:30 <ediardo> So, we did a script that pulls http status codes and explanation messages from 4 core projects
16:18:42 <ediardo> #link And made this website http://172.99.106.155/exceptions/
16:19:06 <etoews> nifty
16:19:15 <ediardo> The idea is to concentrate all API errors into a single place and create a new website under the .openstack.org domain
16:19:28 <elmiko> very cool
16:19:35 <ediardo> we managed to collect ~800 error messages from keystone, nova, cinder and glance,
16:19:51 <etoews> ediardo: this sounds like it's a perfect fit for this http://specs.openstack.org/openstack/api-wg/guidelines/errors.html#errors-documentation
16:19:59 <cdent> etoews: yup exactly
16:20:09 <ediardo> This thing still needs more work, of course, but I want to hear from you guys and know what other similar efforts have been started
16:20:25 <ediardo> Yes
16:20:30 <etoews> none that i'm aware
16:20:32 <etoews> of
16:20:36 <ediardo> I find that example very useful
16:20:44 <edleafe> ediardo: just scanned it briefly - is there anything that points out inconsistencies?
16:21:24 <ediardo> not sure how to answer that question, could you explain a little bit more?
16:21:27 * cdent just noticed he's in the land of nicks that start with 'e'
16:21:28 <etoews> ediardo: you might want to ping sdague about similar efforts but i expect yours is the best going
16:22:01 <edleafe> cdent: you're outnumbered
16:22:10 <cdent> rather
16:23:09 <cdent> ediardo: is there a next step that you're hoping to get from api-wg or is more of a matter of us all nodding and saying "cool"? :)
16:23:38 <ediardo> Those error messages were pulled from the exceptions.py file, some services don't have ALL of the exceptions in this file that's one thing that would require a tedious work
16:23:53 <ediardo> Yes
16:23:58 <etoews> cool
16:24:03 * elmiko nods
16:24:05 <elmiko> cool
16:24:09 <ediardo> I would like to get more direction and people
16:24:27 * etoews something we all want ;)
16:24:30 <ediardo> looks like working with the person you said is the next step
16:25:02 <edleafe> ediardo: sorry, didn't see your question
16:25:21 <edleafe> ediardo: I meant, did you do any comparison of these error messages across projects?
16:25:32 <ediardo> Not yet edleage
16:25:50 <edleafe> ediardo: in the sense of, given a similar exception, projects do/don't handle it the same.
16:26:17 <etoews> that sounds like it might be a step for further down the road
16:26:22 <ediardo> wehaven't done that yet
16:26:37 <edleafe> ok, cool - just wondering where you were with this
16:26:43 <etoews> ediardo: what's the next step you want to take and can we help or have we already done it?
16:26:48 <ediardo> some many stuff could be done once all your base belong to us
16:26:57 <ediardo> sorry, all the api errors belong to us
16:27:32 <ediardo> Should I propose a patch and start the conversation ?
16:27:40 <ediardo> how's the process here?
16:28:07 <cdent> ediardo: it depends on what you're proposing to patch?
16:28:26 <ediardo> A patch with detailed information about this project, how projects would facilitate the collection of api error messages, etc
16:28:37 <ediardo> The JSON Example...
16:29:07 <ediardo> You knoe, come up with a clear vision of where this goes...
16:30:17 <ediardo> any direction will be appreciated
16:30:24 <etoews> ediardo: do you envision this as a "top-level" openstack project?
16:30:29 <cdent> ediardo: I think the project and the plan is a good idea, but it is not something we'd want to hook into the api-wg guidelines until it was further down the road
16:30:47 <cdent> so I'd say that the thing the immediate next steps are:
16:31:01 <cdent> talk to sdague to see if he knows of other things like it
16:31:19 <cdent> post to the os-dev list describing what you're doing and seeking feedback
16:32:07 <ediardo> got it
16:32:27 <etoews> i think this is probably something worthy of being in the big tent at the top-level. considering it seems like it's going to be a running service, questions of care and feeding of said service will come up sooner than later so be prepared to answer those.
16:32:41 <cdent> I suspect that more ideas will come out of the feedback on list
16:33:00 <etoews> ediardo: please prefix the email subject with [api]
16:33:11 <ediardo> etoews: I'll do
16:33:36 <etoews> ediardo: this is good stuff. i look forward to seeing where it goes!
16:33:42 <cdent> yeah, me too
16:33:53 <elmiko> etoews: +1 re: big tent
16:34:10 <ediardo> Thank you guys
16:34:21 <ediardo> We appreciate your feedback
16:35:13 <cdent> cool
16:35:14 * cdent nods
16:35:15 <cdent> :)
16:35:31 <elmiko> lol
16:35:34 <cdent> let's skip the porcelain thing, as it will keep
16:35:35 <cdent> and leap forward to
16:35:41 <cdent> #topic GET with request body vs. querystring vs. POST (edleafe)
16:35:55 <cdent> #link came up in review https://review.openstack.org/#/c/300178/
16:35:55 <edleafe> oh boy oh oboy oh boy
16:36:08 <cdent> #link with commentary on https://review.openstack.org/#/c/385618/1/specs/ocata/approved/resource-providers-get-by-request.rst
16:36:26 <cdent> #link and references in  http://stackoverflow.com/questions/978061/http-get-with-request-body
16:36:46 <edleafe> So one thing we want to establish guidelines first, and then follow them in Nova
16:37:01 <edleafe> Rather than the other way around, which has been the historical pattern
16:37:09 <elmiko> +1
16:37:43 <edleafe> The question is how to best represent a filter to a GET-like request
16:37:55 <edleafe> traditionally one would use a query string
16:38:06 <edleafe> but some feel that the string could be long and ugly
16:38:24 <edleafe> I'm not very concerned about ugly - after all, it's for computers, not people
16:39:05 <edleafe> Length limits are an issue, but apache can take a string over 8000 chars
16:39:13 <edleafe> I don't see us hitting that
16:39:38 <edleafe> The alternative would be to GET with a body
16:39:47 <edleafe> Although the support for that is very iffy
16:40:14 <edleafe> specifically, caches and proxies are not supposed to support bodies in GETs
16:40:20 <elmiko> i thought there was some question if all the http middleware/frameworks we use support body for GETs
16:40:24 <cdent> (that apache limit isn't a uri limit, it's for "field", and we're not actually sure what that is, the uri limit is longer)
16:40:29 <edleafe> So we are also considering a POST with a body
16:40:45 <edleafe> But many object on the grounds that POST feels like it should be creating resources
16:40:48 <cdent> note also that this etherpad is currently active:
16:40:53 <edleafe> even though the docs say otherwise
16:40:58 <cdent> #link etherpad discussing other proposals: https://etherpad.openstack.org/p/placement-request-providers
16:41:20 <edleafe> cdent: I ran some tests on qs length. Results are in the same etherpad
16:41:47 <cdent> oh cool, thanks edleafe
16:41:56 <cdent> so anyway, there are two issues here:
16:42:08 <edleafe> elmiko: exactly, which is why we've been pushing back on the GET+body approach
16:42:12 <cdent> one is resolving the problem in a correct way and making a guideline for this kind of thing
16:42:48 <elmiko> hmm
16:42:50 <cdent> two is dealing with projects that express unwillingness to be concerned with standards and guidelines
16:43:05 <elmiko> nothing about this changes that stance though
16:43:13 <edleafe> cdent: well, we obviously need #1 first
16:43:52 <cdent> edleafe: I'm not certain about that ordering: the api-wg has alreayd said: if all else follow the rfcs
16:44:01 <edleafe> we need consensus on a guideline before we can criticize some group for not following it :)
16:44:02 <cdent> the rfcs don't like get with a body
16:44:20 <edleafe> cdent: but they don't prohibit it, either
16:44:28 <cdent> they prohibit it meaning anything
16:44:31 <edleafe> cdent: and it will work (most of the time)
16:45:31 <edleafe> So does anyone else have any opinions on this?
16:46:03 <elmiko> in general, i think i lean towards the request params side of the force for shaping a GET
16:46:22 <elmiko> seems easy, but i understand the reasons why ppl may not like it
16:46:34 <etoews> agreed
16:46:46 <etoews> (sorry my internet connection dropped there for a bit)
16:47:07 <etoews> the "the URL is ugly" argument is silly
16:47:45 <etoews> if the URL length limit argument turns out to be valid then other options could be considered
16:48:54 <elmiko> +1
16:49:27 <edleafe> OK, it seems that there is no significant disagreement
16:49:37 <cdent> I think it is important to be able to articulate why this is the better way to go and what a second option should be
16:49:45 <edleafe> How about I write up a proposed guideline?
16:49:47 <cdent> (I think the second option is POST with a body)
16:49:49 <cdent> edleafe++
16:49:53 <etoews> +1
16:50:03 <elmiko> ++
16:50:24 <cdent> #action: edleafe will write up proposed guideline for complex queries
16:50:32 <edleafe> cool
16:50:37 <elmiko> agreed that we should be well rationed about this, but it is one of those gray areas that can descend into religious holy wars
16:50:49 <cdent> the thing that actually enrages me most about this process is people insisting that POST means a write
16:51:00 <edleafe> elmiko: that's exactly why we should have a guideline for that
16:51:09 <elmiko> edleafe: agreed
16:51:25 <edleafe> cdent: in 99% of the cases that's true
16:51:38 <elmiko> cdent: yeah, i mean you could take an extreme position and say that the POST is creating an ephemeral resource which only exists for the lifetime of the request ;)
16:51:41 <cdent> not really, if you consider forms
16:51:58 <cdent> POST has no built in semantics
16:52:11 <cdent> web form post is a complex query
16:52:16 <etoews> that's a side discussion
16:52:24 <elmiko> true, but don't we start to travel a winding road back to "why can't i have action endpoints with POST?"
16:52:36 <etoews> elmiko: do you mind taking the newsletter? i have another meeting after this.
16:52:41 <cdent> etoews: I think it's germane because not understanding what the methods mean is part of what has made these discussions so long
16:52:57 <elmiko> etoews: sure, might take me a few, i have a couple meetings as well
16:52:59 <elmiko> :/
16:53:12 <cdent> elmiko: action endpoints has come up in this discussion too
16:53:21 <elmiko> gotcha
16:53:34 <edleafe> cdent: I see stuff like this all the time explaining REST and HTTP verbs: https://www.ibm.com/developerworks/webservices/library/ws-restful/
16:53:51 <edleafe> They map the verbs to CRUD operations
16:53:59 <cdent> sure and that's bogus
16:54:10 <edleafe> of course
16:54:14 <edleafe> but it's out there
16:54:24 <edleafe> and if you read it on the internet, it has to be true
16:54:43 * cdent is not sure what we're discussing :)
16:54:50 <cdent> anyway we are quickly running out of time
16:54:52 <cdent> and we should hit
16:55:11 <cdent> #topic null/special case in time intervals: https://review.openstack.org/#/c/383862/8
16:55:45 <etoews> cdent: looks like you can workflow+1 https://review.openstack.org/#/c/364460/
16:56:04 <elmiko> i'll get this newsletter out by eob today
16:56:06 <cdent> done
16:56:38 <cdent> i reckonthis can be merged too: https://review.openstack.org/#/c/385128/
16:57:30 <etoews> done
16:57:37 <cdent> rad
16:59:09 <cdent> I reckon that's end of time then
16:59:12 <cdent> any last words?
16:59:19 <cdent> #action elmiko make the newsletter go
16:59:24 <etoews> good day to you fine sirs
16:59:35 <elmiko> later
16:59:36 <edleafe> cdent: end of time? Heavy.
16:59:51 * cdent is catastrophic
17:00:05 <cdent> thanks everyone, we'll have some leftovers for next time
17:00:07 <cdent> #endmeeting