00:00:35 <cyeoh> #startmeeting api wg
00:00:36 <openstack> Meeting started Thu Oct 30 00:00:35 2014 UTC and is due to finish in 60 minutes.  The chair is cyeoh. Information about MeetBot at http://wiki.debian.org/MeetBot.
00:00:37 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
00:00:39 <openstack> The meeting name has been set to 'api_wg'
00:00:52 <cyeoh> Hi is anyone here for the API Workgroup meeting?
00:00:59 <elmiko> o/
00:01:06 <eliqiao> hi gm cyeoh.
00:01:12 <miguelgrinberg> yes, hi
00:02:03 <cyeoh> cool - ok wasn't sure who would be able to attend given summit is next week.
00:02:33 <cyeoh> I don't think I've ever met anyone here in person before so maybe we could start with some intros?
00:03:02 <cyeoh> eg. why you're intested in the API WG (user of API, operator, developer) and what you'd like to contribute.
00:03:30 <stevemar> o/
00:03:40 <stevemar> cyeoh, i'm late!
00:03:51 <cyeoh> I'm happy to start off - I work on the Nova API and I'd like to see a lot more consistency both within the Nova API and across the openstack APIs
00:04:05 <cyeoh> stevemar: hi :-) Just started going around doing some intros
00:04:49 <elmiko> hi, michael mccune here, i'm a developer with red hat and i've been working on the sahara project for the last 7 months or so. recently i've been doing some research into implementing a swagger/wadl generator for our project.
00:05:25 <ycombinator> hi, this is shaunak kashyap. I'm a developer advocate at rackspace
00:05:59 <miguelgrinberg> I'm Miguel Grinberg. I'm a dev with Rackspace. Interested in REST APIs, have been working with Heat and also would like more uniform and more RESTful APIs all around.
00:06:17 <eliqiao> hi, Eli Qiao , work for nova-api , and join openstack from Juno, a fresh man :)
00:06:28 <stevemar> i mostly work with keystone, and just looking for make things a bit more consistent across the APIs :)
00:06:56 <alex_xu> hi, I'm Alex Xu, work on nova API
00:07:31 <cyeoh> cool - I think that's everyone?
00:07:56 <sigmavirus24> I'm Ian. I'm working on openstack sdk right now as I ease into OpenStack
00:08:58 <cyeoh> ok. I don't really have an agenda, so I'm going to wing it a bit
00:09:03 <cyeoh> #topic reviews
00:09:11 <cyeoh> #link https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
00:09:16 <elmiko> sounds good =)
00:09:28 <cyeoh> we have a few in the queue atm
00:09:54 <cyeoh> only one has a -1/-2 at the moment:
00:10:03 <cyeoh> #link https://review.openstack.org/#/c/130690/
00:10:27 <cyeoh> It's the use of 207 multistatus as a response
00:11:06 <cyeoh> Background is that its actually a webdav response originally which we normally avoid, but from what I've seen is more widely used than webdav these days for calls that require multiple status returns
00:11:46 <cyeoh> We currently use it in Nova for registering for external events and had planned on using it for multiple server creation where some can succeed and some can fail
00:12:23 <cyeoh> But given it was originally a webdav response there has been some opposition to standardising on it.
00:12:31 <cyeoh> Does anyone have any opinions on this?
00:12:44 <cyeoh> any suggestions for better alternatives?
00:12:49 <sigmavirus24> So I've been looking for examples of other popular APIs that return a 207 and I can't find any that return a 207
00:13:11 <sigmavirus24> Granted, none of them also allow for batch operations either, so I don't think my search is in anyway conclusive
00:13:58 <elmiko> is 207 specifically used when there is partial completion of the operation?
00:14:00 <cyeoh> sigmavirus24: ok I can go back and have another search again (we first looked at it for nova a couple of years ago and we found a few, but they weren't the big APIs)
00:14:17 <miguelgrinberg> which is the endpoint that returns 207? Can't find it
00:14:28 <cyeoh> elmiko: we only use it when there is at least one failure
00:14:57 <cyeoh> miguelgrinberg: I'll just go look for the nova ref
00:15:38 <elmiko> cyeoh: i haven't read this rfc associated(4918), i'm curious what it has to say
00:16:07 <elmiko> because it seems "multi-status" would be appropriate
00:16:24 <cyeoh> #link http://git.openstack.org/cgit/openstack/nova/tree/nova/api/openstack/compute/contrib/server_external_events.py#n68
00:16:25 <elmiko> is it _only_ supposed to be used for webdav?
00:16:35 <cyeoh> elmiko: its in the webdav rfc
00:16:37 <annegentle> better late than never I always say o/
00:16:42 <sigmavirus24> elmiko: it's a status code defined for webdav which is an extension of http
00:16:47 <cyeoh> annegentle: hi ;-)
00:16:51 <elmiko> got it
00:17:04 <sigmavirus24> as such it should really only be used then but that doesn't prevent people from doing something else
00:17:14 <cyeoh> elmiko: I haven't however managed to find an alternative
00:17:31 <elmiko> right, and this does seem like a situation where a binary pass/fail might not be specific enough
00:17:44 <sigmavirus24> technically teh rfcs allow us to return 227 with a custom reason if we want, but that's still going to be wildly unexpected to anyone who is more familiar with other apis
00:17:58 <elmiko> sigmavirus24: agreed
00:18:06 <cyeoh> yep
00:19:25 <cyeoh> so unless someone points out something better, I think Nova is continue its use of 207 and will use it for server creation as well. I don't know if other projects have a similar need for multi-status?
00:19:27 <elmiko> cyeoh: man... really starting with a tough cookie ;)
00:19:38 <cyeoh> heh :-)
00:19:51 <elmiko> i imagine sahara will have need to multi-status
00:20:11 <elmiko> we don't use it now, but it seems like something we could use
00:21:01 <cyeoh> ok. does anyone here really hate the thought of using 207 across openstack?
00:21:02 <sigmavirus24> would sahara survive without it?
00:21:11 <elmiko> definitely
00:21:32 <elmiko> i meant that to sigmavirus24's question
00:21:46 <annegentle> what does multi-status mean with batch operations?
00:22:03 <cyeoh> annegentle: for async type calls?
00:22:39 <cyeoh> so we haven't used it in Nova for aync type calls, but server creation is an example of this.
00:22:46 <elmiko> cyeoh: i'm curious why not 206, if only part of the operation succeeded it could be returned.
00:23:26 <cyeoh> annegentle: because we do some prechecking in server create we can know for sure that some will fail, though we don't know what will succeed in the end (we plan to use tasks for this)
00:23:27 <sigmavirus24> elmiko: that's typically when the server is delivering a file but doesn't want to transmit it all at once. the client is expected to use teh range headers to request the other parts of the file
00:23:47 <ycombinator> question re: using 207 - does that mean the response will /have/ to be XML?
00:23:52 <sigmavirus24> elmiko: doesn't mean we *couldn't* apprioriate it, just that it seems odd
00:24:06 <annegentle> so you get a 207 until all operations are complete? (I can also ask these on the review, not here)
00:24:23 <cyeoh> ycombinator: no we don't support xml at all
00:24:38 <elmiko> sigmavirus24: yea, a little round hole/square peg, but i imagine if you requested X servers be created and the response was only X-2 were actually created, that's a little similar to a count
00:24:59 <sigmavirus24> elmiko: yeah
00:25:38 <cyeoh> elmiko, sigmavirus24: we kind of could, but we still want to be able return an error code for the failures (they may differ for each failure case)
00:25:50 <miguelgrinberg> I apologize in advance if this doesn't make sense, but if you are sending a request that includes a list of operations in the body, shouldn't the status of said operations be reported in the body of the response, with the response being a 200, regardless of teh status of the individual operations?
00:25:51 <sigmavirus24> If openstack as a whole *really* needs this, I would rather see it be 207 frankly. But if we're going to standardize it off of one project's behaviour (that is already a little odd) I don't know if we should be concerned with it so early
00:26:55 <cyeoh> annegentle: so if some fail/succeed straight away you get a 207. If its an async case and none have failed you get a 202 accept
00:27:44 <elmiko> cyeoh: i feel like we're kinda bumping against the idea from the mailing list of operation status objects. like if you knew some entities failed, why not query those entity's statuses for increased info, if you care to see it.
00:27:51 <cyeoh> sigmavirus24: so if only Nova is doing this I'm ok with it not being standardised, but as soon as another project wants to do a multi-status-type thing then I think we should do it all the same
00:28:20 <annegentle> ok thanks cyeoh... I'm looking for other apis needing this now...
00:28:26 <sigmavirus24> cyeoh: yeah that's kind of what I'm thinking. That said, I agree with miguelgrinberg. I'm not sure I understand the need for a separate status code in this case
00:29:00 <miguelgrinberg> the status code of the response applies to the operation as a whole, not the individual sub-operations
00:29:22 <cyeoh> well a 207 is a success code right?
00:29:32 <stevemar> technically
00:29:49 <stevemar> i guess it means at least 1 operation was successful?
00:29:59 <cyeoh> not that we should really return a 200 in the server create case because its async
00:30:12 <sigmavirus24> a 200 response with an array of successes and an array of failures is good too
00:30:48 <cyeoh> sigmavirus24: yep, though thats essentially doing a 207 type content, just returning 200 instead isn't it?
00:31:17 <elmiko> cyeoh: i would think you will check the return object anyways, so why not 200?
00:31:47 <cyeoh> so the way we've used it so far (only one case) is we return 200 if everything succeeds
00:31:58 <cyeoh> so you don't need to check any further
00:32:13 <cyeoh> if we have at least one failure then we return 207.
00:32:27 <etoews> no please
00:32:30 <cyeoh> with details about the individual fail/succeeds
00:32:45 <etoews> don't return different success codes based on some logic
00:32:55 <ycombinator> I think the response code should be same regardless of # of failures
00:33:04 <miguelgrinberg> can you return a more expected 4xx if at least one operation failed?
00:33:06 <etoews> same return code with same body interpreted the same way every time.
00:33:21 <elmiko> have to say, i'm seeing the 200 side of this as being a little clearer
00:33:38 <annegentle> there's a progress attribute returned now, right?
00:33:49 <cyeoh> annegentle: nope, we don't have tasks yet
00:34:03 <annegentle> cyeoh: ah.
00:34:21 <cyeoh> and before we have tasks we need to implement microversions....
00:34:35 <etoews> cyeoh: are you aware of any examples of a 207 being used in the wild?
00:34:44 <cyeoh> (unfortunate long chain of dependencies)
00:34:55 <cyeoh> etoews: in openstack or outside of openstack?
00:35:00 <etoews> both
00:35:24 <cyeoh> etoews: so in openstack we use it for os-external-server-events
00:35:45 <annegentle> cyeoh: there's a progress: 0-100% returned in v2.0 now
00:36:09 <cyeoh> annegentle: is that the instance actions thing?
00:36:30 <annegentle> I see it in GET servers/detail
00:36:59 <annegentle> cyeoh: maybe it never goes up from 0? :)
00:37:04 <ycombinator> question: what does an "all operations successful/in-progress" response body look like? is that documented somewhere? maybe that will help steer toward a certain status code
00:37:32 <cyeoh> etoews: for outside I don't have any references handy but did at the time a couple of years ago (I can come back later with some probably)
00:37:43 <cyeoh> annegentle: i suspect it might not
00:38:15 <cyeoh> annegentle: instance actions was sort of an interim progress thing before someone came up with the tasks proposal
00:39:28 <etoews> cyeoh: k. it would just be interesting to see some other examples. (if you can't find any i wouldn't consider that a blocker though)
00:40:27 <cyeoh> etoews: ok there were a few at the time - basically I was looking for a way to do multi-status and didn't want to invent something. anyway I'll get back to the group
00:40:44 <etoews> ycombinator: is this sort of what you were looking for? https://wiki.openstack.org/wiki/Nova/ExternalEventAPI
00:40:49 <cyeoh> ycombinator: there might be some in the nova api samples for server-external-events
00:41:08 <ycombinator> yeah, thanks
00:41:30 <cyeoh> ok well I didn't intend for this topic to suck up so much time, maybe we should shelve it for a bit (I can come back with more info)
00:41:57 <sigmavirus24> cyeoh: sounds like a good idea. Maybe put it on the agenda for next week or the week after
00:42:14 <elmiko> sigmavirus24: +1
00:42:15 <cyeoh> sigmavirus24: ok, will do. I'm assuming no irc meeting next week because of summit
00:42:49 <cyeoh> I think this one should be a lot less controversial:
00:42:54 <cyeoh> #link https://review.openstack.org/#/c/131358/
00:43:33 <annegentle> cyeoh: one question, have we determined the voting for "merge"
00:43:34 <cyeoh> just advertising it because its a proposal for the process of how we vote on changes etc.
00:43:36 <sigmavirus24> cyeoh: I hope it's less controversial, for the meeting's sake ;)
00:44:05 * annegentle reads more
00:44:39 <cyeoh> heh. so I'm fine with the fairly short notice for changes to guidelines while we're still bootstrapping.
00:44:45 <stevemar> hopefully it is :)
00:45:47 <annegentle> yeah I think it's okay, but commenting in the review itself
00:45:52 <elmiko> cyeoh: looks solid to me, i might make the time a little longer for #3 bit i agree about the bootstrapping period.
00:46:05 <cyeoh> what is not yet defined is who can vote when it comes to contentious issues
00:46:24 <annegentle> cyeoh: you might consider exceptions around known busy times like milestones
00:46:42 <stevemar> cyeoh, PTLs seems like a good idea
00:46:43 <cyeoh> annegentle: oh good point - milestones and summit when people just get really busy
00:47:09 <annegentle> I definitely think we need +1 from any affected PTL for the process.
00:47:41 <cyeoh> annegentle: so for contentious issues or all of them?
00:47:43 <sigmavirus24> annegentle: do we want to require PTL participation or should there be a cross project person that the project/ptl chooses?
00:47:59 <cyeoh> sigmavirus24: I think we assume the PTL can delegate?
00:48:06 <annegentle> So who gets to count as one of the four +1s? That's way too small a number in my mind.
00:48:50 <annegentle> I think we have to get PTL involvement, and with the cross-project and integration emphasis coming, it can just be the 2 affected PTLs.
00:48:52 <cyeoh> annegentle: at the moment anyone because we're trying to get some momentum. Maybe we need a PTL rep vote before the 1.0 release?
00:48:56 <annegentle> so it might vary
00:49:04 <annegentle> and I do think PTLs can designate a voter
00:49:25 <annegentle> this will all have to be encoded in the infra anyway so might as well say what we want/think will work.
00:49:53 <annegentle> there are now 20 REST API definitions for integrated/incubated
00:50:01 <annegentle> I think we'll need 10-12 +1s
00:50:15 <stevemar> annegentle, whered you find that so quickly :)
00:50:29 <cyeoh> annegentle: do we need that many at this stage though?
00:50:42 <annegentle> stevemar: I live/breath/eat this stuff :)
00:50:54 <sigmavirus24> annegentle: this early in the life of the working group though?
00:50:57 <cyeoh> annegentle: I suspect we're not going to have that much interest from projects until we have something substantial?
00:51:03 <annegentle> cyeoh: are you following much of the "layers" discussion?
00:51:07 <sigmavirus24> I could see growing towards that, but not right now
00:51:12 <annegentle> cyeoh: we need to build interest
00:51:13 <etoews> ya. i'm concerned about making this too process heavy too early too and killing momentum.
00:51:34 <annegentle> etoews: not too heavy, just need votes and interest
00:51:40 <cyeoh> annegentle: re: layers, only a bit (read a few blog posts)
00:52:17 <annegentle> etoews: it's a balancing act - if guidances merges unexpectedly and people get grumpy they weren't "asked" they're less likely to comply
00:52:44 <cyeoh> annegentle: so we'll be clearly marked as draft for now
00:52:45 <annegentle> etoews: so we need to give people votes and voices. I'm for more votes mo' bettah
00:52:56 <annegentle> cyeoh: ah well that's one way to handle it, heh.
00:53:02 <annegentle> cyeoh: merge all you want then!
00:53:29 <cyeoh> annegentle: heh. well we can do a clear PTL delegated vote before moving out of draft
00:53:33 <annegentle> still think we'll need vested PTLs -- TC is definitely interested
00:53:49 <annegentle> cyeoh: okay then that approach solves my concerns :)
00:53:49 <cyeoh> annegentle: and a reasonable long review time before draft goes to vote.
00:54:11 <annegentle> it might go to the TC for the final, is that okay with us?
00:54:12 <cyeoh> annegentle: cool :-)
00:54:19 <etoews> annegentle: true enough. to me that that still seems like a lot of time from a lot of people.
00:54:20 <sigmavirus24> cyeoh: yeah I think that's very fair. that's kind of how I was imagining this would go as we moved towards making this a standards thing
00:54:32 <cyeoh> annegentle: I think that would be good to get the TC to formally review it
00:54:48 <sigmavirus24> Most groups, like IETF working groups will through together a draft in private and then ask for comments. We're doing it in public but it's also very different
00:54:57 <annegentle> we'll still have to be careful about chunks... not overwhelming people in reviews nor drafts
00:55:12 <etoews> so what we're discussing here is all very "top down".
00:55:22 <annegentle> I think we can move quickly as a small WG
00:55:51 <etoews> what about (initially anyway) a more "bottom up" approach where we draft guidelines and use those guidelines in reviews.
00:56:45 <etoews> although i certainly agree having the TC and PTLs aligned with us is great.
00:57:26 <sigmavirus24> etoews: for example, we come up with a draft and look for reviews that it might affect and offer feedback to see if we can influence the review?
00:57:50 <etoews> sigmavirus24: exactly
00:57:51 <cyeoh> etoews: so I think even in draft people will start following them if they seem reasonable (and have some reasoning as to why)
00:57:54 <sigmavirus24> a more, go forth and see if we can convince others that it's a better idea to do X than Y using the draft as X?
00:58:06 <annegentle> etoews: that works until a PTL disagrees with you on a review, but it's a great approach for making the guidelines stick!
00:58:45 <ycombinator> don't want to go down a rabbit hole, but what incentive to projects have to follow these guidelines?
00:58:47 <sigmavirus24> annegentle: and hopefully by that point, that draft hasn't been suggested for use and accepted in too many places because then it might need to be changed
00:58:56 <etoews> right. i'd just like to see us come at this both from the top down (TC and PTL) and bottom up (API WG members doing reviews).
00:59:26 <cyeoh> ycombinator: so the inconsistencies I've mostly seen within Nova have been due to people not knowing and so making stuff up. I think we just start with guidance first
00:59:29 <annegentle> etoews: definitely like "review guidance, pronto" then we also see where any areas lie that need more consensus building
00:59:39 <annegentle> cyeoh: heh good point
00:59:51 <cyeoh> ycombinator: if we need more stick then thats probably something the TC should be doing
01:00:07 <ycombinator> right, I'm thinking if there's a carrot instead
01:00:31 <cyeoh> ycombinator: we print stickers :-)
01:00:35 <elmiko> lol
01:00:44 <ycombinator> heh
01:00:49 <etoews> getting +1's from API WG members on your reviews is a pretty good carrot.
01:01:04 <etoews> and stickers.
01:01:09 <cyeoh> etoews: agreed ;-)
01:01:16 <cyeoh> anyway I think we're out of time.
01:01:25 <etoews> 1 more thing.
01:01:28 <cyeoh> meet again in 2 weeks or is that too soon after summit?
01:01:39 <etoews> the APIImpact flag that didn't appear on the web page.
01:01:43 <annegentle> that'll help keep momentum
01:02:01 <elmiko> cyeoh: +1 for 2weeks
01:02:15 <cyeoh> etoews: yea I saw your comment I haven't had a chance to hunt that down yet. Odd since its been published once at least.
01:02:33 <etoews> okay.
01:02:43 <annegentle> cyeoh: I think it didn't get built it's because it's not part of index.rst any more
01:02:52 <annegentle> too many it's
01:03:01 <etoews> it's okay
01:03:10 <cyeoh> annegentle: ok I'll try submitting a patch which adds the templates back in
01:03:20 <annegentle> cyeoh: ok
01:03:33 <annegentle> thanks cyeoh for running this meeting!
01:03:40 <elmiko> yea, thanks!
01:03:44 <ycombinator> yes, thanks!
01:03:48 <etoews> anyway. i'd like to send the idea of APIImapct out to openstack-dev when it gets published to encourage other programs to do the same.
01:03:55 <etoews> thanks for everything cyeoh!
01:04:01 <cyeoh> thanks everyone for attending!
01:04:06 <cyeoh> #endmeeting