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