00:08:11 <ycombinator_> #startmeeting api wg
00:08:12 <openstack> Meeting started Thu Nov 13 00:08:11 2014 UTC and is due to finish in 60 minutes.  The chair is ycombinator_. Information about MeetBot at http://wiki.debian.org/MeetBot.
00:08:13 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
00:08:15 <openstack> The meeting name has been set to 'api_wg'
00:08:39 <ycombinator_> #topic roll call
00:08:47 <ycombinator_> Shaunak Kashyap, Rackspace
00:10:15 <sigmavirus24> Ian Cordasco, Rackspace
00:10:43 * sigmavirus24 looks at miguelgrinberg
00:10:51 <miguelgrinberg> Miguel Grinberg, Rackspace (heh)
00:10:58 <ycombinator_> #topic agenda
00:11:01 <ycombinator_> https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
00:11:15 <ycombinator_> actually I think that should be #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
00:11:46 <sigmavirus24> I think the first topic would be "Summit Review" anyway
00:12:02 <ycombinator_> #topic summit review
00:12:14 <ycombinator_> @sigmavirus24, @miguelgrinberg were either of you at the summit?
00:12:24 <miguelgrinberg> No
00:12:25 <sigmavirus24> I don't think either of us were, no
00:12:56 <ycombinator_> okay, should we skip to the next topic then?
00:13:17 <miguelgrinberg> was there any related discussions in Paris?
00:13:33 <ycombinator_> I wasn't at the summit either so I can't say
00:13:33 <sigmavirus24> miguelgrinberg: judging by the etherpad, yes
00:13:38 <sigmavirus24> https://etherpad.openstack.org/p/kilo-crossproject-api-wg
00:13:46 <ycombinator_> thanks @sigmavirus24
00:14:16 <miguelgrinberg> maybe we push it for later when others that were there join?
00:14:32 <ycombinator_> sounds good to me
00:14:58 <ycombinator_> #topic additional meeting time
00:14:59 <ycombinator_> https://review.openstack.org/#/c/132668/
00:15:10 <sigmavirus24> Looks like it was already accepted
00:15:34 <ycombinator_> yeah, its on the agenda but I think its already done
00:15:36 <sigmavirus24> So next week's meeting will be 4 hours earlier :)
00:15:48 <sigmavirus24> e 8 hours
00:15:55 * sigmavirus24 keeps thinking it's 2000 utc still
00:16:02 <miguelgrinberg> yeah, it's 8 I think
00:16:17 <ycombinator_> yeah 8 hours earlier
00:16:19 <miguelgrinberg> 8am for me :-(
00:16:43 <ycombinator_> hold on, won't it be 16 hours later?
00:17:11 <sigmavirus24> don't listen to me about timezones
00:17:31 <miguelgrinberg> it's 8 hours earlier time of day, but it is the next day, so yes, 16 hours later
00:17:37 <ycombinator_> haha, ok
00:17:49 <ycombinator_> moving to next item in agenda :)
00:18:03 <ycombinator_> #topic wiki page updates
00:18:06 <ycombinator_> #link https://wiki.openstack.org/wiki/API_Working_Group
00:18:43 <ycombinator_> I'm not sure what there is to do on this one
00:18:46 <ycombinator_> do either of you know?
00:19:16 <miguelgrinberg> maybe review this? I don't know, looks pretty good to me
00:20:14 <sigmavirus24> yeah it's much fuller than it used to be
00:20:24 <sigmavirus24> Looks a lot better than it did pre-summit
00:20:36 <ycombinator_> yeah, I don't have anything to add on this item
00:21:01 <ycombinator_> #topic APIImpact flag
00:21:09 <ycombinator_> #link https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z
00:21:31 <ycombinator_> for these, maybe we can go through the -1 and -2 reviews?
00:22:04 <ycombinator_> #link https://review.openstack.org/#/c/132342/
00:22:09 <sigmavirus24> I think we can do that after the meeting
00:22:31 <sigmavirus24> It looks like most of them are cyeoh and etoews adding requirements for APIImpact to projects
00:23:45 <ycombinator_> yeah, most of them appear to be just that
00:24:16 <miguelgrinberg> I don't see much to comment on either
00:25:55 <ycombinator_> okay... moving on then
00:26:09 <ycombinator_> #topic review 201-header-and-body
00:26:15 <sigmavirus24> https://review.openstack.org/#/c/133087/
00:26:18 <ycombinator_> #link https://review.openstack.org/#/c/133087/
00:27:11 <sigmavirus24> So I agree with cyeoh's most recent feedback that async operations should be 202. 202 best fits that case
00:27:37 <miguelgrinberg> I have provided as much justification I could find for not requiring a body (i.e making it a recommendation, but optional)
00:27:38 <sigmavirus24> Otherwise, I agree with miguelgrinberg about representations being optional
00:28:06 <sigmavirus24> If we can get etoews to address those concerns I think we'll have something that everyone but Sam will approve
00:28:06 <ycombinator_> if the representation is optional, shouldn't the response code be 204, then?
00:28:21 <miguelgrinberg> I'm also in agreement with cyeoh
00:28:21 <sigmavirus24> ycombinator_: 204s shouldn't be used for creates semantically
00:28:42 <sigmavirus24> There are APIs which also return a short representation of the resource instead of returning nothing
00:28:43 <ycombinator_> right, I agree with 201 for synchronous create and 202 for asynch create
00:29:06 <sigmavirus24> 201s don't require a body, just a 0 Content-Length if there is no body
00:29:07 <ycombinator_> but if we don't return any representation, are we required to use 204/
00:29:14 <sigmavirus24> No
00:29:23 <miguelgrinberg> I would say no to the 204, it's too odd
00:29:33 <sigmavirus24> Just like right now when methods for a route aren't defined, we return a 404 instead of the proper 405
00:29:34 <miguelgrinberg> I prefer a 201 with empty body
00:29:59 <sigmavirus24> 405 would be the canonical response to something like that (and something every framework gives us for free) but we don't do it
00:30:02 <ycombinator_> ok, if 201 with empty body is acceptable by spec, that makes sense to me for synch creation
00:30:21 <sigmavirus24> So I mean, we can define OS-REST but I'd really rather not have something that is our own standard *just because*
00:30:31 <sigmavirus24> 201 explicitly signals "created"
00:30:39 <sigmavirus24> which is the information we want to know.
00:30:49 <miguelgrinberg> right, 204 does not confirm creation
00:30:50 <sigmavirus24> 204 is typically tied to "no content" which is terribly ambiguous
00:31:13 <miguelgrinberg> plus, I have never seen 204 tied to a location header
00:31:21 <sigmavirus24> ditto
00:31:30 <miguelgrinberg> I have seen 201 and 202 w/location header, that is pretty standard
00:31:38 <ycombinator_> yeah, me too
00:31:48 <ycombinator_> but I've also never seen a 201/202 without a body
00:32:03 <ycombinator_> all that said, I can't find anything in the HTTP spec that says a 201 must have a body
00:32:13 <sigmavirus24> You won't because it doesn't have to have a body
00:32:28 <sigmavirus24> :)
00:32:42 <ycombinator_> right, so I'm down with 201 for synch creation and 202 for asynch creation (with or without body)
00:32:53 <ycombinator_> so what's the next step here? :)
00:33:06 <miguelgrinberg> location header mandatory or optional?
00:33:19 <miguelgrinberg> if it is optional, then that means that it is somewhere in the body
00:33:26 <miguelgrinberg> which can be confusing
00:33:30 <ycombinator_> I'd say mandatory, even if the link is in the body
00:33:34 <ycombinator_> rather, the link in the body is optional
00:33:36 <miguelgrinberg> +1
00:33:39 <sigmavirus24> +1
00:33:44 <ycombinator_> but having the location header makes it uniform
00:33:49 <miguelgrinberg> even for the 202
00:34:00 <miguelgrinberg> though for a 202 it may not be a resource link
00:34:10 <miguelgrinberg> it can be a get-status link for a resource that doesn't exist yet
00:34:14 <sigmavirus24> mhm
00:34:18 <sigmavirus24> +1
00:34:22 <miguelgrinberg> you may not know the resource link
00:34:24 <ycombinator_> +1
00:35:01 <sigmavirus24> so should someone take over this patchset and amend it with what's been discussed here?
00:35:09 <ycombinator_> yes, I can do that
00:35:16 <ycombinator_> to confirm, I captured two things:
00:35:34 <ycombinator_> 1. synchronous creation should respond with 201, asynchronous with 202; body is optional
00:35:56 <ycombinator_> 2. in either synchronous or asynchronous creation, there must be a location header
00:35:59 <ycombinator_> correct?
00:36:09 <miguelgrinberg> looks good to me
00:36:11 <sigmavirus24> #action ycombinator_ will update https://review.openstack.org/#/c/133087/ with 1. synchronous creation should respond with 201, asynchronous with 202; body is optional and 2. in either synchronous or asynchronous creation, there must be a location header
00:36:18 <ycombinator_> thanks @sigmavirus24
00:36:27 <sigmavirus24> you're welcome I constructed it as you spoke :)
00:36:30 <ycombinator_> moving to next item
00:36:43 <ycombinator_> #topic reviews
00:36:47 <ycombinator_> #link https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
00:37:14 <sigmavirus24> So I'd like to discuss https://review.openstack.org/#/c/132248/ and https://review.openstack.org/#/c/131320/
00:37:31 <sigmavirus24> The first we've just agreed against and we should probably point that out to Sam
00:37:47 <sigmavirus24> The second is what my mini-rant was about above
00:38:10 <miguelgrinberg> so cyeoh complains that it may be impractical to implement the 405
00:38:29 <miguelgrinberg> I suggested he looks at my proposal for the heat API, which generates the 405s and the Allow header automatically
00:39:02 <sigmavirus24> And since that seems like it might be desirable in other libraries, we should probably move it into oslo-incubator if we can get dhellmann's approval
00:39:57 <ycombinator_> @sigmavirus24 do you want to take an action for commenting on the first one for Sam?
00:40:09 <sigmavirus24> ycombinator_: certainly
00:40:23 <miguelgrinberg> agreed
00:40:32 <ycombinator_> #action sigmavirus24 will comment on https://review.openstack.org/#/c/132248/ re: no 204 for creation
00:40:34 <miguelgrinberg> it should be part of the framework
00:40:52 <sigmavirus24> If you're talking about Routes, I discussed this with Ben and he vehemently disagreees
00:41:00 <sigmavirus24> Unless you want to bring it up again
00:41:10 <sigmavirus24> It could also be a third party package that's maintained and not included in oslo at all
00:41:22 <sigmavirus24> That may be harder to have added to global-requirements.txt though
00:41:33 <sigmavirus24> Unless this review is approved
00:41:35 <miguelgrinberg> I mean framework in a relaxed way, maybe something on top of the routes pkg
00:41:44 <sigmavirus24> Fair enough
00:42:00 <miguelgrinberg> or we should just switch everything to Flask and be done with it ;-)
00:42:12 <sigmavirus24> smh
00:43:11 <etoews> hi
00:43:17 <ycombinator_> hi :)
00:43:33 <sigmavirus24> hey etoews
00:43:41 <sigmavirus24> we started without you, hope you don't miind
00:43:48 <etoews> not at all
00:44:10 <ycombinator_> sigmavirus24, miguelgrinberg: so what's the next step on https://review.openstack.org/#/c/131320/?
00:44:18 <etoews> so sorry i'm late. i could've sworn it was 7 pm for me.
00:44:39 <annegentle> yeah DST got a few of us :)
00:44:40 <miguelgrinberg> I think we need to talk to cyeoh
00:44:40 <sigmavirus24> ycombinator_: coming to a decision about whether we want to enforce the standard of every other API on OpenStack regardless of convenience
00:44:43 <ycombinator_> after this one we can circle back to the first couple of items on the agenda
00:45:01 <sigmavirus24> ycombinator_: unless there are other reviews people would like to highlight/discuss
00:45:18 <etoews> yes
00:45:19 <ycombinator_> right
00:45:35 <etoews> https://review.openstack.org/#/c/133087/
00:45:40 <ycombinator_> miguelgrinberg: do you want to take the action on initiating the conversation with cyeoh?
00:45:50 <miguelgrinberg> yes, I can do that
00:45:56 <etoews> #link https://review.openstack.org/#/c/133087/
00:46:02 <ycombinator_> #action miguelgrinberg to start conversation with cyeoh re: https://review.openstack.org/#/c/131320/
00:46:36 <sigmavirus24> etoews: thoughts?
00:46:39 <etoews> that's the proposal i started at the summit with the entire group present.
00:46:53 <sigmavirus24> Right
00:47:24 <etoews> sadly i haven't even had a chance to really review the comments since i got back :(
00:47:41 <sigmavirus24> etoews: it's okay :) we discussed it earlier
00:48:14 <sigmavirus24> the arguments are as follows (for a tl;dr): 1. 201s body should be recommended but optional
00:48:28 <sigmavirus24> 2. 201s should always have a Location header pointing to the created resource
00:48:47 <etoews> that's reasonable.
00:48:53 <ycombinator_> or a status resource, right sigmavirus24 ?
00:48:56 <sigmavirus24> 3. 202s should be returned for asynchronous creation tasks and should include a Location header (which does not need to be the resource URL)
00:49:02 <ycombinator_> nvm - 201
00:49:04 <ycombinator_> continue
00:49:37 <sigmavirus24> Even though a 201 may have no body, it's better (and more consistent) to return a 201 to signal successful creation than a 204 which has no intrinsic meaning of "yes we created that"
00:50:52 <sigmavirus24> Basically cyeoh asked for the 202 specific information to be included. We all agree with them on that. Miguel is requesting that we not ever use 204 for POSTs whose representation is too large to reasonably returned in a 201
00:51:43 <etoews> one of the things we discussed at the summit was being opinionated and using strong language (like "must") in our proposals. if we get good counter arguments, we can adjust the language. makes for better history and stronger guidelines.
00:52:28 <miguelgrinberg> I like the stronger language, but that may put some of the APIs at fault until the rev their specs to comply
00:52:30 <sigmavirus24> I'm not sure I follow
00:52:43 <etoews> i'll read the eavesdrop and the review comments and update the proposal for 201-header-and-body
00:53:17 <ycombinator_> thanks etoews
00:53:54 <etoews> miguelgrinberg: so we don't want to use language that encompasses current practice. we want to use language that encompasses best/preferred/recommended practice, regardless of what the current apis do.
00:54:06 <miguelgrinberg> fine with me
00:54:17 <miguelgrinberg> just pointing out that it may look confusing
00:54:45 <sigmavirus24> etoews: that sounds excellent
00:55:24 <ycombinator_> #action etoews to update proposal for 201 header and body in https://review.openstack.org/#/c/133087/
00:55:36 <ycombinator_> any other reviews to go over?
00:55:52 <ycombinator_> also, we have 5 minutes left technically
00:56:43 <etoews> that's one of the things that came up in the design summit. what to do about "old" apis that don't follow the guidelines. i updated the deliverables and #5 reflects that. https://wiki.openstack.org/wiki/API_Working_Group
00:57:31 <etoews> #topic additional meeting time
00:57:43 <etoews> so that review was accepted.
00:57:48 <sigmavirus24> yep
00:58:02 <etoews> personally (obviously?) that time works a bit better for me.
00:58:11 <etoews> i'll be switching to that one.
00:59:08 <etoews> #topic wiki page updates
00:59:13 <etoews> i updated the wiki
00:59:21 <sigmavirus24> the updates look awesome. thank you
00:59:30 <etoews> based on feedback at the summit.
00:59:31 <etoews> please to review :)
00:59:47 <etoews> i'll try to send out a summit summary sometime this week.
00:59:59 <etoews> summit summary sometime summit summary sometime summit summary sometime
01:00:15 <etoews> aaaaaaand time
01:00:59 <ycombinator_> #endmeeting