00:00:05 #startmeeting api wg 00:00:05 Meeting started Thu Feb 5 00:00:05 2015 UTC and is due to finish in 60 minutes. The chair is etoews. Information about MeetBot at http://wiki.debian.org/MeetBot. 00:00:06 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 00:00:08 The meeting name has been set to 'api_wg' 00:00:16 hiya 00:00:18 hi 00:00:20 hi! 00:00:25 hello 00:00:26 hey 00:00:44 hey cyeoh! good to have you back. 00:00:50 o/ 00:00:53 etoews: thx :-) 00:00:54 cyeoh: long time no see 00:01:06 etoews: I'm pretty sure miguelgrinberg wont' make it tonight 00:01:16 k 00:01:18 #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda 00:01:52 we currently have 2 big matzah balls out there 00:02:17 mission statement and which repo to use 00:02:26 #topic mission statement 00:03:01 have people been following the thread on the ml? 00:03:08 yup 00:03:18 sorry missed it, is there a draft up somewhere? 00:03:43 yep 00:03:58 cyeoh: don't think we made it to draft phase yet 00:04:09 cyeoh: http://lists.openstack.org/pipermail/openstack-dev/2015-February/055763.html 00:04:23 sigmavirus24: thx 00:04:25 cyeoh: actually it starts http://lists.openstack.org/pipermail/openstack-dev/2015-January/055694.html 00:04:30 #link http://lists.openstack.org/pipermail/openstack-dev/2015-January/055694.html 00:04:35 #link http://lists.openstack.org/pipermail/openstack-dev/2015-February/055763.html 00:04:46 there are some nice suggestions in the thread 00:05:43 yes. it's been helping me think about it. 00:06:31 I'm not sure what the value of "pragmatic" is in that context to be honest 00:06:43 But it doesn't bother me. It just seems superfluous 00:07:12 I like "pragmatic" because (to me) it drives home that we're looking for implementable, practical solutions 00:07:54 I'd hope we can make it slightly fewer words still. If something else can be tightened that makes more room. 00:08:14 But it feels like it has developed nicely. 00:08:19 i like stefano's suggestion about including our audience 00:08:33 so I like the bit about identifying existing practice because I don't think we should be very cautious about recommending anything that hasn't been tried in practice yet 00:08:59 +1 cyeoh 00:09:07 that seems to be harmonious with "practical" imo 00:09:20 So I think there are two things that people are talking about simultaneously in that thread: 1. elevator pitch 2. full mission statement 00:09:28 yes 00:09:36 We might want to develop the former from the latter and the latter should be longer form than initially proposed 00:10:24 cyeoh: my hesistancy with that is the implication that we'll favor existing (insufficient) openstack API designs over better and not unattainable designs that have been implemented successfully outside of openstack 00:10:43 +1 sigmavirus24 00:10:54 sigmavirus24: +1 00:11:09 By which I mean, it should be made clear that we won't only be pulling from prior art of OpenStack and nothing more 00:11:20 sigmavirus24: well thats a possibility, but recommending something that turns out not to work at all is even worse 00:11:37 especially if multiple projects adopt it because its in the guidelines 00:11:44 i'm all for breaking a few eggs to make things better, at the same time we have to hammer home the "guidelines not standards" message 00:11:55 here's what i originally envisioned. 1-3 sentences of text describing our purpose. which could be followed by longer text going into more detail. 00:12:04 == elmiko 00:12:29 for example, I wouldn't have a recommendation for microversions in the document yet until we actually see it working in Nova 00:12:38 cyeoh: fair 00:12:42 makes sense 00:12:53 +1 elmiko but i think there's a caveat that one day particular guidelines could become a standard. 00:12:55 but I think it would be ok to have something saying"this is what Nova is trying, might want to consider it" 00:12:56 for example, I want to see metadata sent via headers killed because there are so many issues that other projects have run into 00:13:09 etoews: yeah, i kinda left of ", yet..." from the end ;) 00:13:23 I think we're all in agreement though =) 00:13:34 cyeoh: i would go further by saying to not include it until client code has been written against it too. 00:13:53 let's hammer out something! 00:13:56 etoews: agreed 00:14:06 something we can take back to the ml 00:14:24 etherpad? 00:15:11 http://etherpad.openstack.org/p/api-wg-mission-statement 00:15:16 #link http://etherpad.openstack.org/p/api-wg-mission-statement 00:15:55 +1 00:16:54 perhaps we should move on? 00:17:20 * sigmavirus24 pings etoews 00:17:32 we can go through and update the etherpad further after the meeting 00:17:45 can we give this 5 more minutes? 00:18:05 *really wants to hammer something out* 00:19:00 okay 00:19:15 so I kind of like Dean's the best, but I would like to add something that says we're a group that can be approached if a project is not sure about something not covered by the existing guidelines 00:19:26 s/can/should/ 00:21:29 I like Dean's as well, just trying out some different wording options 00:21:47 cyeoh: yeah. If miguelgrinberg were here though, he could attest to the fact that every time we're approached for advice people are expecting a rubber stamp, not actual constructive criticism 00:22:14 Dean's does have a nice compactness to it 00:22:22 sigmavirus24: we'll give them constructive criticism anyway :-) 00:22:49 my one issue with Dean's is, as sigmavirus24 pointed out, we should also look beyond OpenStack for existing practices 00:22:58 cyeoh: righto, they can't stop us from sending emails. 00:23:03 stevelle: good point 00:23:31 to me dean's leaves too many questions open. the kind of questions we've been getting from the people we're trying to engage 00:24:21 moving the "OpenStack REST APIs" fixes stevelle's issue, so we're collecting implementations/best practices and bringing them into openstack 00:24:21 i think we could distill a tweetable mantra out of something slightly longer form. 00:24:23 yea, would be nice to mention guidelines in there somewhere, i think we have to 00:24:33 i prefer ryan's over dean's because it says API convergence, not project convergence 00:24:38 elmiko: +1 00:24:52 thanks to whoever fixed my grammar. ;) 00:24:58 rosmaita: +1 00:25:37 ryansb: it wasn't me but I would have been proud to have done so 00:25:41 == rosamita 00:25:42 also dean's doesn't say for who or why 00:26:51 well this is the API-WG mission statement, I think that covers "who" 00:26:57 why though. Good point. 00:27:20 ryansb: so who is the who? 00:27:22 i'd like if we could add stefano's improve dev experience to ryan's second statement 00:27:24 ryansb: why? because we should 00:27:57 put another way, who is our audience? 00:28:22 API consumers == developers ? 00:28:33 +1 rosmaita identifying the why in naming the developer experience 00:28:34 well ultimately I see it to make life as easy as possible for the users of the OpenStack APIs (not openstack developers generally) 00:28:37 That's the hardest one to answer since we consumer our APIs via our python-*client s and openstacksdk 00:29:08 sigmavirus24: yep I'd definitely include those people 00:29:39 that's my thinking as well. our audience is the api consumers. 00:29:39 sigmavirus24: I guess I mean to stay its not primarily for those writing the api implementations, though it certainly helps 00:29:46 cyeoh: right 00:29:46 i don't see "improve developer experience" implying openstack devs 00:29:58 +1 to rosmaita's point about API consumers == developers 00:30:04 though it would definitely include them 00:30:14 I think the other thing is that the python-*clients often mirror the respective APIs in the CLI so this will provide a more consistent cli for users as well (e.g., operators in this case) 00:30:32 the who is "API-WG" for "distill" and the why is "to make developers happier" IMO 00:30:39 this is why it's so important to clearly identify the audience. developers actually has double meaning in openstack 00:30:58 (sorry to jump in unnoticed, felt like a strong case to vote) 00:31:03 there are developers building apps on openstack and developers contributing to openstack 00:31:11 in this case (I think) it's both kinds 00:31:12 welcome, nikhil_k 00:31:12 is "API consumers" OK? would cover everyone 00:31:23 stevelle: :) 00:31:35 rosmaita: something along those lines 00:31:35 consumers of openstack (app builders/tool builders) and producers of openstack (openstack contributors) 00:31:49 rosmaita: +1 00:31:53 i think we should use different language than "API consumers" 00:32:08 == elmiko 00:32:24 I don't know what better language exists though 00:32:25 it's especially important because if we just use the word developers, the "producers of openstack" will assume it's them that's being talked about 00:32:42 hmm, sticky wicket... 00:32:59 it just seems axiomatic that the API-wg is talking to API consumers 00:33:12 argh, etherpad connection failures. 00:33:17 API patrons 00:33:19 ok, how about "to improve the OpenStack experience" ? 00:33:20 to me API consumers doesn't just mean people though, it also means applications etc. 00:33:27 nikhil_k: +1 i like patrons 00:33:53 sigmavirus24: that's a good point too, plus we are talking to api creators as well 00:34:06 hrm I think patrons might just confuse people 00:34:16 probably, but sounds cool 00:34:19 point of order, we have spent 20 minutes on this so far 00:34:44 stevelle: good point to order 00:35:16 i'm willing to move if people pinky swear to chime in on the ml 00:35:36 s/move/move on/ 00:35:44 is there an emoticon for that? 00:35:48 * elmiko pinky swears 00:35:54 rosmaita: lol 00:35:57 #topic api guideline repo 00:36:05 * ryansb \nnnn pinky swears 00:36:19 we decided on 1 repo. so which one? openstack-specs or api-wg 00:36:29 i'm leaning towards api-wg 00:36:30 i'm +1 for api-wg 00:36:31 +1 for api-wg 00:36:51 +1 00:36:54 if we ever need to truly make something a standard, it can be proposed to openstack-specs 00:36:56 rosmaita: \mXm/ 00:37:04 yea, api-wg 00:37:04 nikhil_k: good one! 00:37:07 nikhil_k: LOL +1 00:37:09 nikhil_k: nice! 00:37:21 legit 00:37:36 * rosmaita \mXm/ 00:37:38 well, at the least we figured that mystery out ;) 00:37:40 let me throw this thought out there. 00:38:01 what if we changed how we wrote guidelines to be a bit more spec-like 00:38:17 each guideline becomes its own doc 00:38:31 with section for examples, prior art, motivation, etc. 00:38:43 too much process/overhead? 00:38:52 i like that approach 00:39:02 * sigmavirus24 too 00:39:06 etoews: I'd prefer at the moment to concentrate on getting something out soon 00:39:16 or would it short circuit a lot of the discussion that goes on in the review? 00:39:17 i think it woudl be worth the trouble 00:39:27 as in ensure we can do a release in Kilo 00:39:43 well cyeoh definitely has a point there 00:40:04 i feel like it's the discussion asking for examples, prior art, motivation, etc. that's slowing us down 00:40:05 I would like to see process evolve in the next cycle. 00:40:13 * sigmavirus24 wasn't aware we were planning a release in kilo 00:40:16 etoews: i would think they would have the same level of discourse, just in a spec review instead. 00:40:26 planning this for the next cycle makes sense though 00:40:36 sigmavirus24: +1 00:40:50 so I like the idea of prior art, motivation etc, but I think its something we can add in the future 00:41:38 alright. i just wanted to throw it out there for thought. 00:41:41 i can certainly get on board with planning a spec-like change for the M cycle 00:42:12 er L, whatever is next lol 00:42:17 #startvote do we use the api-wg repo to write our guidelines? 00:42:18 Begin voting on: do we use the api-wg repo to write our guidelines? Valid vote options are Yes, No. 00:42:19 Vote using '#vote OPTION'. Only your last vote counts. 00:42:31 #vote use the api-wg repo 00:42:35 #vote Yes 00:42:35 or #yes 00:42:39 #vote yes 00:42:39 #vote yes 00:42:46 #vote yes 00:42:47 #vote yes 00:42:54 #vote yes 00:42:56 #vote yes 00:43:16 do I get to vote? 00:43:26 yep 00:43:32 (doesn't seem to matter now though) 00:43:37 #vote yes 00:43:49 as far as i'm concerned. you're here and you care. you get to vote. 00:43:49 nikhil_k: stil... best to be heard =) 00:44:03 #endvite 00:44:07 elmiko: :) 00:44:08 #endvote 00:44:08 Voted on "do we use the api-wg repo to write our guidelines?" Results are 00:44:38 #agreed we use the api-wg repo to write our guidelines 00:45:07 #action etoews to take vote result to ml 00:45:20 #topic Glance and functional API 00:45:33 #link https://etherpad.openstack.org/p/glance-adding-functional-operations-to-api 00:45:34 #link https://review.openstack.org/#/c/135122 00:45:37 o/ 00:45:50 * sigmavirus24 thanks etoews for noticing that 00:46:30 Hi, miguelgrinberg sigmavirus24 stevelle hemanth and I had a small :) discussion last evening (EST) on this topic 00:46:52 It was suggested to bring it up here for the reasons of 00:47:02 1. Finding the best possible approach 00:47:29 2. Keeping the project goals intact and solving the API guideline issue at hand 00:47:56 The proposal is 00:48:33 adding ' POST /v2/images/{image_id}/actions/{action_type} ' to Glance existing APIs set 00:48:57 (on line 102-5 in the etherpad) 00:50:11 This is to enable a operation of the likes of " being able to deactive a malicious/unusable/licence revoked image and stop the booting process until operators find a good way to fix the image (or its data) 00:50:30 The reasons for that proposal are listed here, lists.openstack.org/pipermail/openstack-dev/2014-May/036416.html 00:51:02 That being the primary use case; some others were proposed in ATL summit (to which I'm still trying to dig the info out) 00:51:03 so is an action actually being created? or is it strictly a functional point in time thing? 00:51:24 functional point in time 00:52:43 etoews: also you're POST'ing without a body 00:52:51 (iirc) 00:53:07 sigmavirus24: yrc 00:53:29 rosmaita: ty 00:53:37 and what if one day the glance api needed to do an action that needed multiple parameters. some of which might be complex? 00:53:58 Also: The project design needs to keep 'status' field non-writable (from the client/user's perpective); it should happen from within the code. 00:54:17 Ah yes, nikhil_k's constraint is an important one 00:54:27 100% agreed that the status field is non-writable. 00:54:35 :) 00:55:00 so let me at least throw this out there. 00:55:06 http://developer.openstack.org/api-ref-compute-v2-ext.html#ext-os-instance-actions 00:55:10 so the execution of an action ultimately has an effect on the representation of the resource it acts upon 00:55:33 the nova api apparently actually creates an action resource 00:55:49 (for that particular extension anyway) 00:56:07 i don't think we want to do that here 00:56:13 etoews: right, glance seems to have ruled that out at the Atlanta Summit 00:56:17 in that case I personally think the use of "actions" might be legit, even if I'd say it should be a PUT because at the end of the day the goal of the API is modifying the status of the resource once the task associated with the action completes 00:56:20 This seems to be more of an on/off switch though 00:56:51 i read it like the use case of those action resources is as an audit log 00:56:59 fwiw, neutron API implements this kind of construct for attaching or detaching interfaces from a router 00:57:05 etoews: I felt similarly 00:57:20 rosmaita: can you tl;dr that decision 00:57:21 ? 00:57:41 well, we had just introduced tasks into glance 00:57:45 i thought it was bad form to tunnel controller like commands through a single endpoint? 00:57:45 as actual entities 00:58:01 that track long-running asynchronous operations 00:58:11 this just seemed like a different kind of thing 00:58:20 elmiko: it is, which is why miguelgrinberg and I are not fond of it 00:58:28 sigmavirus24: ack, thanks 00:59:10 elmiko sigmavirus24: do you have a reference for why it's bad form. something that might help everyone understand? 00:59:27 fwiw instance-actions in nova will basically go away once we have tasks 00:59:40 cyeoh: good to konw 00:59:57 but a lot of those instance-actions actually are better modelled as tasks 01:00:00 as operations are async what are the proposed solutions to track the progress of a operation, if I might ask? 01:00:01 That's v3 though, right? 01:00:10 etoews: my only reference is the o'reilly rest design book, i'll see if has an argument though 01:00:18 nikhil_k: well v2.1 microversions ;-) 01:00:22 elmiko: thx 01:00:25 ahh 01:00:29 etoews: well, miguelgrinberg will love this, but it's certainly not HATEOAS for one 01:00:49 dang. we're at time. 01:00:54 #endmeeting