16:00:10 <cdent> #startmeeting api wg
16:00:15 <openstack> Meeting started Thu Mar 23 16:00:10 2017 UTC and is due to finish in 60 minutes.  The chair is cdent. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:16 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:00:19 <openstack> The meeting name has been set to 'api_wg'
16:00:22 <edleafe> \o
16:00:27 <cdent> #chair cdent elmiko edleafe
16:00:28 <openstack> Current chairs: cdent edleafe elmiko
16:00:55 <cdent> Any elmiko today? Anyone else along for the api-wg?
16:01:23 <cdent> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
16:01:31 <cdent> #topic previous meeting action items
16:01:32 <stevelle> o/
16:01:42 <cdent> #link http://eavesdrop.openstack.org/meetings/api_wg/2017/api_wg.2017-03-16-16.00.html
16:02:01 <cdent> only action item was on edleafe to adopt the pagination guideline and he did it!
16:02:06 <cdent> success
16:02:13 <edleafe> woo hoo!
16:02:40 <cdent> it was also agreed that I should go back to bed, which I did, and though my cold still lingers, I'm much less poorly
16:02:45 <elmiko> o/
16:02:58 <elmiko> \o/
16:03:03 <cdent> #topic open mic and new biz
16:03:18 <cdent> * clarify api-wg is tc governed not uc governed
16:03:27 <elmiko> uc?
16:03:33 <cdent> there's been some confusion on whether we are "governed" by the tc or the uc (user committee)
16:03:38 <knikolla> o/
16:03:40 <elmiko> ahh
16:03:48 <edleafe> confusion where?
16:04:05 <stevelle> ML
16:04:06 <cdent> the reason for some of the confusion is that the UC has us on some wiki pages and regularly contacts us about setting up time at summits and such
16:04:20 <cdent> and in some presentations to the board the api-wg was "claimed" by the UC
16:04:29 <cdent> so this inspired some asking around about what the truth was
16:04:59 <cdent> and the truth is that api-wg is under the guidance of the tc and we need to make sure we're on the right wiki pages etc and off the wrong ones
16:05:01 <elmiko> interesting
16:05:07 <edleafe> You can't handle the truth!!
16:05:11 <elmiko> LOL
16:05:18 <cdent> the basic dealio is is whether we meet at the ptg or ops meetups
16:05:23 <elmiko> you need me on this firewall!
16:05:39 <cdent> since it is the ptg for us, that makes us tc
16:05:43 <elmiko> ptg seems more appropriate though
16:05:54 <elmiko> sorry, i'll stop interrupting now
16:05:55 <cdent> i haven't yet located the who and what we need to clean up
16:06:07 <edleafe> ptg++
16:06:09 <cdent> so if people know or find stuff, feel free to take it upon yourself to tidy
16:06:15 <elmiko> ack
16:07:17 <cdent> and presumably when emails start going round about UC stuff to the api-wg cores, we should let them know what's up
16:07:48 <cdent> I've got a couple other new biz things that I only thought of today so are not on agenda, but before I monopolize, anyone else got something? stevelle?
16:08:06 <stevelle> I'm just here for the bagels
16:08:15 <cdent> bagels!?!?
16:08:36 <stevelle> I was promised bagels and cream cheese
16:08:36 <cdent> edleafe: did you eat all the bagels before giving me one?
16:08:56 <edleafe> Nope. I refuse to eat bagels that aren't from the NYC area
16:09:01 <elmiko> ooh, now i'm hungry... thanks stevelle !
16:09:04 * edleafe is a bagel and pizza snob
16:09:12 * cdent is not shocked
16:09:12 <elmiko> edleafe hahaha
16:09:15 * stevelle is a helper
16:09:32 <cdent> okay, then I'll take back the floor:
16:10:13 <cdent> in conversation today about "what the api-wg does" there was an assertion that we produce guidelines, as in that's our job
16:10:43 <cdent> I demurred suggesting that was a byproduct of our job, which is to work towards creating consistency and correctness in openstack apis
16:10:51 <cdent> thoughts?
16:11:29 <edleafe> Those two do not seem orthogonal
16:11:33 <cdent> indeed
16:11:49 <edleafe> IOW, the way to create consistency and correctness is via the guidelines
16:11:54 <dstanek> cdent: besides the docs how else is that done?
16:12:00 <cdent> the way or a way?
16:12:11 <elmiko> i guess the question is how much "creating consistency and correctness" do we do beyond producing guidelines?
16:12:17 <cdent> dstanek: by talking a lot and scrupulously encouraging input from lots of voices
16:12:37 <cdent> what I just said to dstanek is the crux of the biscuit
16:12:37 <edleafe> ...so that we can create better guidelines!
16:12:42 <elmiko> good point cdent, we also help to facilitate the conversation
16:12:52 <dstanek> cdent: sure, but the product is the docs - that's what most people will see
16:13:31 <elmiko> imo, i think it's good not to gloss over the social factors that we bring to bare
16:13:34 <dstanek> the hard part of software engineering isn't the code, but unfortunately many see us as just 'coders'
16:13:34 <dtroyer> dstanek: _one_ product is the docs, the primary product is better APIs
16:13:36 <cdent> yeah, the reason this came up and the reason I'm bringing it up here is because of some disagreement over the extent to which I've made efforts to keep the conversations on the stability guideline ongoing
16:14:00 <edleafe> dtroyer: no, that is the goal
16:14:06 <dstanek> i like the 'the way' language as it shows a stonger opinion
16:14:08 <edleafe> we don't produce any APIs
16:14:38 <dstanek> dtroyer: i'm not disagreeing...i'm just saying why people think it's just docs
16:14:39 <dtroyer> not directly, but that is one of the things that people should see
16:14:58 <stevelle> the indirection between the better apis makes it difficult to do more than infer correlation
16:15:22 <stevelle> between the better apis and the concrete products of the WG...
16:15:51 <dtroyer> so maybe it is better said in the form cdent used, producing those conversations that lead to better APIs?
16:15:55 <edleafe> We do arbitrate to some degree when there are disagreements
16:15:59 <dstanek> stevelle: ++
16:16:18 <edleafe> But we don't produce APIs
16:16:46 <dstanek> i see this group as 'architects' in a more traditional architecture role
16:16:52 <elmiko> dtroyer: +1
16:17:06 <cdent> huh, apparently it is a good thing I brought this up, as it has revealed yet more (mild) disconnects. That's good.
16:17:06 <edleafe> stevelle: precisely. Our existence will help reduce the number of "this is my preference" decisions that can go different ways depending on the developer
16:18:23 <cdent> I'm not sure there is a particular action we can take from this, other than to consider it as a question for a while "What is that we do?"
16:18:36 <edleafe> eat bagels?
16:18:40 <elmiko> ++
16:18:41 <dstanek> i mention the agi-wg quite a bit when we are designing features (like tages and other apis) - sometimes i get asked when it is
16:19:05 <dstanek> it would be nice to have a clear, cohesive statement if one doesn't exist
16:19:13 <dstanek> mission statement of whatever
16:19:13 <cdent> there is a mission statement
16:19:18 * jroll walks in late
16:19:24 <cdent> http://specs.openstack.org/openstack/api-wg/
16:19:53 <cdent> but I'm not sure if it gets what we've actually done over the past couple of years
16:20:07 <elmiko> maybe time for a refresh?
16:20:41 <cdent> I dunno. That's definitely _not_ what I was thinking of when I raised the topic. But if other people think so.
16:21:07 <edleafe> elmiko: thanks for volunteering! :)
16:21:15 <elmiko> XD
16:21:20 <dstanek> that sounds after the fact. i usually say that this group looks and what we have, best practices and helps us architect better apis
16:22:05 <elmiko> here's another angle
16:22:28 <elmiko> in the past we have made serious effort to document what is happening in the openstack world through our "current design" wiki
16:22:34 <elmiko> that is definitely another thing we produce
16:23:10 <elmiko> granted, it's more r&d, but still
16:23:57 <cdent> So it seems there more to think about then I originally assumed. Should we articulate an agenda item for next week to think about in the interim (so that we can move on now)?
16:24:46 <elmiko> could we hold till the week after? (i'm out for kubecon next week)
16:24:50 <cdent> sure
16:25:01 <elmiko> thanks
16:25:01 <cdent> as long as you pay the forfeit of creating the agenda item
16:25:10 <elmiko> definitely
16:25:32 <cdent> #action elmiko to make an agenda item to think about what we do
16:25:39 <elmiko> haha, beat me to it
16:26:44 <cdent> next thing is the concrete incident of "keeping the conversation open". We need to bring the stability guideline to a close and the alternatives section is causing some stress. I've put some options in my last comment. we should figure it out and get on with things[1]
16:26:55 <cdent> #link https://review.openstack.org/#/c/421846/
16:27:21 <cdent> [1] which is not to say we'll be done, we haven't even made it to freeze on this thing yet, so there may be yet more rounds of debate
16:27:49 <elmiko> LOL i *love* option 4
16:27:56 <elmiko> but, i think i'd vote for option 2
16:28:01 <edleafe> I was about to add to the review, but if this is a guideline that will be used as the basis for a particular TC tag, we should only have one recommendation
16:28:16 <elmiko> ooh, good point edleafe
16:28:47 <elmiko> i could definitely get on board with that line of thinking
16:28:56 <jroll> isn't the alternative to every api-wg spec, to ignore the spec? which is a valid option, as the api wg isn't a mandate but a recommendation?
16:29:00 <jroll> edleafe: ++
16:29:02 <edleafe> I don't think we'll ever get agreement from everyone
16:29:06 <elmiko> jroll: right
16:29:15 <elmiko> probably no need to tell folks that explicitly
16:29:34 <edleafe> So we need to record the overall consensus
16:29:58 <cdent> I'd like to avoid the situation where the guideline doesn't have enough info in it to avoid the common questions of "why aren't you doing _____ instead"
16:30:19 <dtantsur> cdent++
16:30:31 <jroll> that's fair
16:30:31 <cdent> if we can rely on people reviewing the gerrit record then no problem
16:30:33 <edleafe> cdent: that's different than providing alternatives
16:30:43 <cdent> but if we can't then we need something
16:30:52 <cdent> edleafe: yes, thus one of the options being "rename the section"
16:31:03 <jroll> we often treat the 'alternatives' section in ironic like that - "how else could this be done, and why aren't we doing that?"
16:31:23 <elmiko> if we leave it in, i agree we need to change the language
16:31:24 <edleafe> cdent: Or integrate those ideas into the rest of the document
16:31:39 <cdent> that's a reasonable 5th option yes
16:31:55 <edleafe> IOW, we reccommend X. We considered Y, but because of Z we rejected it
16:32:46 <edleafe> jroll: but a spec and a guideline are two different beasts
16:32:53 <cdent> edleafe: does it make sense for you to write a new patch fulfilling that option?
16:32:56 <cdent> (the option 5)
16:33:23 <jroll> edleafe: sure, just thought that data point might be useful
16:34:16 <cdent> *crickets*
16:35:16 <edleafe> The main problem is that there are people who simply do not like microversions
16:35:31 <edleafe> Some of it is based on misunderstanding how they work
16:35:41 <edleafe> Some is based on fears of misapplication
16:35:59 <elmiko> some is technical ;)
16:36:10 <dtantsur> ++
16:36:18 <rosmaita> some of it is fear of overhead and instability (of the implementation, not the api)
16:36:32 <edleafe> "Microversions are the worst system for API stability, except for all the others"
16:36:40 <elmiko> LOL
16:36:41 <cdent> the walls have ears!
16:37:01 <elmiko> cdent: i was just thinking the same, mention "microversions" and the channel really perks up
16:37:02 <cdent> in some sense microversions are not germane
16:37:32 <stevelle> I have been tumbling around the ideas of alternatives to microversions and all I have right now is the opportunity to talk about an API maturity model
16:37:46 <edleafe> elmiko: I thought if mentioning free bagels didn't attract a crowd, nothing would :)
16:37:47 <stevelle> similar to Graham's comments
16:37:56 <elmiko> edleafe++ haha
16:38:21 <edleafe> stevelle: I'd love to see that
16:38:45 <cdent> the document goes out of its way to say "microversion are the available tool, but even they weren't, we've still got all these issues witt changes that impact stability"
16:38:50 <edleafe> because I'm having a hard time figuring out how Graham's approach would work in the actual OpenStack world
16:38:51 <stevelle> edleafe: great, we can hold that for thinking later
16:39:16 <mugsie> edleafe: well, designate did it pretty successfuly
16:40:00 <dtantsur> my personal problem with microversions is not microversions themselves. it just look to me like a solution seeking for problems. hence my nitpicks on "why" and use cases.
16:40:54 <cdent> let's roll back a bit
16:40:57 <mugsie> my problem with microversions is that I do not think 90% of users will use them as they are so complex
16:41:01 <edleafe> mugsie: I didn't follow designate's development history, so I'd have to read more on their problems and solutions
16:41:29 <dtantsur> mugsie, no worries, we force them into using microversions (usually in a wrong way) by hiding features in old versions :/
16:41:39 <cdent> edleafe: are you willing to write up a modification of the document in the way described by your option 5?
16:41:47 <edleafe> mugsie: interesting. The main point of microversions is that 90% of people will never have to know anything about them :)
16:42:09 <edleafe> cdent: perhaps next week, as I'm on 50% PTO this week
16:42:12 <mugsie> apart from the pewople who write tooling, or apps that talk to apis, or libraries
16:42:21 <dtantsur> edleafe, this never worked like that (mostly due to bad implementations, not bad idea)
16:42:49 <cdent> does anyone object to the option 5 idea which is to talk about the alternative in the body of document, rather than its own section
16:43:11 * jroll doesn't
16:43:22 <mugsie> cdent: depends on how it is proposed - it if is "this other way is wrong", I do
16:43:27 <edleafe> In the Nova case, the 2.1 behavior is exactly the same. No new tooling or clients have needed to change to get a stable response
16:44:00 <elmiko> cdent: no objection here
16:44:35 <edleafe> mugsie: would you be willing to propose your alternative?
16:44:53 <edleafe> IOW, have two proposals that people can compare?
16:44:54 <cdent> #action edleafe to explore the apocryphal option 5 on the stability guideline
16:45:05 <mugsie> edleafe: yes, but not for a few days
16:45:35 <edleafe> mugsie: that's cool, since it doesn't seem like this thing is going to be solved in the immediate future
16:46:04 <mugsie> edleafe: ++
16:46:17 <edleafe> cdent: I'd prefer to wait until I can read mugsie's proposal to write up a new version
16:46:37 <edleafe> cdent: it seems like there is a lack of clear understanding on both sides as to what the other is talking about
16:46:51 <cdent> that's okay with me, but there's some (minor) time pressure because of the tag stuff, but I don't think it matters that much
16:47:12 <dtantsur> cdent, I think it's important to define a tag that people will want to get
16:47:16 <cdent> from my standpoint I just need to pass this particular ball to good hands
16:47:29 <cdent> dtantsur: good point
16:47:31 <dtantsur> as it's written now, I don't quite care about this tag for ironic, even though we probably comply with the guideline
16:47:54 <cdent> k, let's move on?
16:48:00 <cdent> # topic guidelines
16:48:04 <cdent> #link https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
16:48:29 <cdent> jroll made a new one, which has had some interesting debate that probably needs to be resolved
16:48:39 <cdent> #link add next_min_version https://review.openstack.org/#/c/446138/
16:48:45 <dtantsur> cdent, your #topic did not work btw
16:48:54 <cdent> dtantsur: thanks whoos
16:48:58 <cdent> #topic guidelines
16:49:15 <jroll> yeah, there's just oen wedge in mine
16:49:31 <cdent> and I think maybe perhaps pagination might be close?
16:49:37 <cdent> #link pagination https://review.openstack.org/#/c/446716/
16:50:01 <cdent> and max length is a bit confused
16:50:12 <cdent> #link max length tags: https://review.openstack.org/#/c/447344/
16:50:22 <edleafe> The pagination started to descend into wanting implementation details
16:50:51 <elmiko> yeah, that whole pagination ordering thing seems out of scope for the api guideline
16:50:59 <elmiko> but maybe i'm just being myopic on this one
16:51:12 <edleafe> elmiko: yeah
16:51:14 <cdent> we should but more of our eyes on that, and it should be ready to freeze for next week (it has no current reviews)
16:51:17 <elmiko> that just smells like a per-project issue depending on how they handle resources
16:51:21 <cdent> s/but/put/
16:51:38 <edleafe> more like per query/resource
16:51:41 <elmiko> the point that Qiming made about 404, _may_ be valid. not sure
16:51:57 <cdent> the 404 thing is weird
16:52:04 <cdent> 404 is always weird with collection resources
16:52:24 <elmiko> yeah
16:52:47 <elmiko> this is like the issue we had awhile ago about returning 404 if a referenced resource in the body json is not there
16:52:55 <edleafe> I thought of 410 instead
16:53:10 <edleafe> Gone
16:53:12 * elmiko looks up 410
16:53:26 <elmiko> ahh, yeah
16:53:35 <cdent> 410 is for signifying very permanent goneness
16:53:43 <cdent> and could apply to the url without parameters
16:53:44 <edleafe> BUt yeah, applying a single resource construct to a collection is weird
16:53:46 <cdent> that's the issue here
16:54:24 <edleafe> A 'next' request is saying "give me some more resources, starting with this one"
16:54:49 <cdent> s/with/after/ ?
16:54:54 <edleafe> When "this one" is gone, how do we react?
16:55:20 <cdent> (5 minutes)
16:55:43 <edleafe> cdent: well, yea
16:55:47 <edleafe> yeah
16:55:55 <edleafe> same idea, thoguh
16:55:58 <edleafe> jeez
16:55:58 <dtantsur> I still feel like it's 404, dunno...
16:55:59 <edleafe> though
16:56:19 <edleafe> It's definitely an edge of an edge case
16:56:26 <cdent> edleafe: you've been spending too much time with my typing
16:56:45 * edleafe starts filtering cdent from his IRC client
16:57:01 <cdent> #topic bugs
16:57:04 <cdent> #link https://bugs.launchpad.net/openstack-api-wg/+bugs?orderby=-id&start=0
16:57:18 <cdent> there's one new one, which is about tag lengths, mentioned above
16:57:31 <cdent> so it is in progress, but some indecision on need to have it or not
16:57:52 <cdent> #topic weekly newsletter
16:57:58 <cdent> #link https://etherpad.openstack.org/p/api-wg-newsletter
16:58:18 <cdent> I guess I'll do it this week and ping people in for a proof
16:58:22 <cdent> any last words?
16:58:26 <elmiko> muchas gracias
16:58:38 <edleafe> "Either these curtains go..."
16:58:44 <elmiko> LOL
16:58:44 <jroll> thanks cdent
16:59:04 <cdent> despite our assertions last week that we were a bit quiet lately, seems there are actually many things to talk about
16:59:07 <cdent> I guess that's good
16:59:15 <elmiko> yeah, totally!
16:59:17 <dtantsur> :)
16:59:27 <elmiko> good attendence today, thanks all =)
16:59:37 <cdent> thanks everyone for coming and helping make it interesting
16:59:39 <dtantsur> thanks!
17:00:01 <cdent> #endmeeting