16:00:04 <cdent> #startmeeting api_wg
16:00:05 <openstack> Meeting started Thu Aug 18 16:00:04 2016 UTC and is due to finish in 60 minutes.  The chair is cdent. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:06 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:00:08 <openstack> The meeting name has been set to 'api_wg'
16:00:16 <cdent> #chair elmiko etoews
16:00:16 <openstack> Warning: Nick not in channel: elmiko
16:00:16 <etoews> o/
16:00:17 <openstack> Current chairs: cdent elmiko etoews
16:00:31 <cdent> oh noes, no elmiko
16:01:01 <cdent> who, besides etoews and I, is here for api-wg?
16:01:21 <cdent> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
16:01:31 <cdent> #topic previous meeting action items
16:01:39 <cdent> #link http://eavesdrop.openstack.org/meetings/api_wg/2016/api_wg.2016-08-11-16.00.html
16:01:57 <cdent> only action from that was me trying to hook up gerrit and launchpad, review in progress at
16:02:13 <cdent> #link https://review.openstack.org/#/c/355885/
16:02:43 <cdent> so new biz:
16:02:53 <rosmaita> o/
16:02:53 <cdent> #topic making capabilities a cross project thing
16:03:03 <cdent> ah, good rosmaita, nice to see you
16:03:06 <etoews> i saw the email thread
16:03:44 <cdent> basically I'd like to make sure that if we're going to have capabilities discovery it is the same from service to service
16:04:05 <cdent> even better would be if it were aligned with some kind of global emerging standard
16:04:13 <cdent> but that's often hard to do in this context
16:05:48 <etoews> cdent: by capabilities, surely you mean traits ;)
16:06:00 <cdent> heh, in this case I actually mean capabilities :(
16:06:06 <cdent> it's all very confusing
16:06:15 <etoews> oh. yep. now i'm confused.
16:06:37 <etoews> it what your talking about different from the ML thread?
16:06:47 <cdent> there are two threads from the mailing list
16:06:49 <etoews> s/your/you're/
16:07:46 <etoews> cdent: wait. this has rabbit hole written all over it. let's find out what rosmaita would like to chat about first.
16:07:51 <cdent> one is the discussion of the jaypipes' library, initially named os-capabilities which got renamed to os-traits. These are things that a resource provider can do. for example a shared disk service might have a a trait of "ssd". an adjectival description of a quality available from this thing. compute hosts would have them for machine ops and such
16:08:15 <cdent> two is what a use can do at service (such as upload an image file)
16:08:27 <cdent> going point etoews, rosmaita you got something ?
16:08:52 <rosmaita> well, i have 2 things actually
16:08:54 <cdent> s/going/good/
16:08:56 <rosmaita> first one is related to this
16:08:58 <cdent> yay! two things
16:09:09 <rosmaita> we are implementing some discovery in glance for the image import refactor
16:09:12 <rosmaita> we called it "value discovery"
16:09:13 <rosmaita> it doesn't quite map to "capabilities" (at least I don't think so)
16:09:20 <rosmaita> https://specs.openstack.org/openstack/glance-specs/specs/mitaka/approved/image-import/image-import-refactor.html#value-discovery
16:09:57 <rosmaita> my question is whether this still looks OK
16:10:07 <rosmaita> we planned it before the capabilities stuff took off
16:10:20 <rosmaita> so i don't want glance to do something non-standard
16:11:22 <rosmaita> the idea is each deployer will expose this doc, but the values are likely to be unique to a deployment
16:12:09 <rosmaita> and, it is specific to importing images, not a general statement about the capabilities of the image service
16:12:25 * etoews reads
16:12:28 <cdent> this looks a bit more detailed that what I of as capabilities, but I'm not sure I really know enough about the capabilities plans to be sure about that
16:12:48 <rosmaita> yes, it is focused on a very specific use case
16:13:13 <rosmaita> anyway, please keep it in mind as you think about the other stuff
16:13:20 <rosmaita> in case you detect any conflicts
16:14:02 <rosmaita> that's all for my first topic
16:14:31 <cdent> #action (everyone) keep an eye on https://specs.openstack.org/openstack/glance-specs/specs/mitaka/approved/image-import/image-import-refactor.html#value-discovery as it may relate to the ongoing capabilities discussion
16:14:43 <rosmaita> thanks!
16:14:57 <cdent> second?
16:14:59 <rosmaita> the second one is a general api kind of question
16:15:03 <rosmaita> about versioning
16:15:08 * cdent prepares a shed
16:15:12 <rosmaita> the images api is not microversioned
16:15:53 <rosmaita> and, tbh, the milliversions or deciversions, whatever you call the minor number after the dot, have not always been bumped appropriately
16:15:58 <rosmaita> but that's all in the past
16:16:23 <rosmaita> anyway, my question is, if you are versioning like we are, e.g., 2.1, 2.2, 2.3
16:16:38 <rosmaita> suppose that some improvements are made to some query string parameters
16:16:51 <rosmaita> like for listing images
16:17:18 <rosmaita> say, adding support for the api-wg approved way of expressing them
16:17:32 <rosmaita> would that type of change entail a minor version bump
16:17:39 <rosmaita> (he says, hoping the answer is no)
16:17:41 <rosmaita> ?
16:18:15 <cdent> It depends a lot on who you ask and what you want microversions to signal or mean?
16:18:37 <etoews> rosmaita: is your concern about bumping because that version is in the URL?
16:18:50 <cdent> If the behavior is only adding something, and not breaking any pre-existing behavior, and is not changing any representations, then I would say "no"
16:19:12 <rosmaita> cdent: ok, that's what we were thinking too
16:19:15 <rosmaita> etoews: sort of
16:19:28 <rosmaita> let me give you some context for this question, it's the api-ref
16:19:49 <etoews> i'm agreed with cdent, especially if it means changing the URL.
16:20:02 <rosmaita> i was wondering whether we should have a particular version of the api-ref associated with each stable release
16:20:29 <rosmaita> sdague pointed out that we should just have an ongoing ever-accurate api-ref
16:20:51 <rosmaita> but nova has microversions, and i think for the query parameter situation i described, they introduce a new microversion
16:21:06 <rosmaita> but since we aren't microversioned, that doesn't help
16:21:12 <etoews> ya
16:21:23 <rosmaita> i guess what's really at stake is who the consumers of the api-ref are
16:21:24 <cdent> yes, nova tends to microversion whenever there's a hint that it might make sense
16:21:54 <cdent> rosmaita: I think you need to trust that human's are adaptable and can, will and should read stuff when things go wrong
16:22:00 <cdent> sigh: humans
16:22:12 <rosmaita> you see the problem for glance ... the newton api-ref may be the same version as mitaka, but not everything described in that will work in mitaka
16:22:46 <rosmaita> or is this not something to worry about?
16:22:57 <cdent> If the doc is being written mostly by hand is it okay to say something like "since x.y.z you can use params foo=bar"
16:23:03 <cdent> in a ..note:: ?
16:23:17 <rosmaita> except we don't have a z
16:23:34 <cdent> well i was being generic, that could be a date, or a realease name, or what have you
16:24:03 <rosmaita> ok, so a release name would be acceptable?
16:24:04 <cdent> just some identifier, any identifier, that people can discover
16:24:32 <cdent> the issue that people are trying to solve is when you move from one cloud to another that things break _and_ you can't figure out why
16:24:34 <rosmaita> ok, that's good
16:24:48 <cdent> if you can figure out why, somehow, then the sin is much less dire
16:25:21 <etoews> personally i'm not crazy about that stuff in docs. the docs tend to become littered with such things and it forces devs to do a little mental calculation every time they hit one.
16:25:21 <rosmaita> the problem is that there's no way to really discover whether you have a liberty 2.3 images api or a mitaka 2.3 images api
16:25:34 <etoews> that's the rub
16:25:37 <rosmaita> etoews: exactly
16:26:03 <cdent> rosmaita: if that's really true, then you don't have actually have a 2.3 and a 2.3
16:26:07 <cdent> you have a 2.3 and something else
16:26:18 <etoews> microversions would help this case.
16:26:21 <cdent> yes
16:26:21 <rosmaita> i guess that's why microversions were invented
16:26:23 <rosmaita> yes
16:27:21 <rosmaita> cdent: that's probably true, about the 2.3 and something else, but that boat has sailed
16:27:32 <rosmaita> guess we can just vow to be better in the future
16:27:42 <cdent> microversions are useful, despite being a bit hammer-making-lots-of-nails-ish
16:28:33 <rosmaita> ok, well this was a helpful discussion
16:28:37 <rosmaita> thanks!
16:28:55 <cdent> in your situation, in the older version when the new parameter is used, what would happen? failure of some kind or just ignoring it?
16:29:35 <rosmaita> i think mostly just ignoring
16:29:38 <etoews> rosmaita: back to your capabilities question. fyi, dramakri brought up something that looked similar a couple of weeks ago #link http://eavesdrop.openstack.org/meetings/api_wg/2016/api_wg.2016-08-04-16.00.log.html
16:29:47 * cdent nods
16:30:00 <rosmaita> though there may be some weird stuff with the time formats that causes 400s
16:30:09 <etoews> #link https://review.openstack.org/#/c/306930/12/specs/newton/discovering-system-capabilities.rst
16:30:13 <rosmaita> etoews: thanks for the link, will look
16:31:03 <etoews> he was going to start a guideline about it but we haven't heard back yet and i didn't see his name on the ML discussion about capabilities.
16:31:39 <etoews> take it fwiw, don't hold up your dev over it.
16:33:11 <rosmaita> ok thanks
16:33:18 <rosmaita> that's all from me
16:33:33 <cdent> I think we've had enough about capabilities in general so move on?
16:33:55 <cdent> #topic non-JSON apis and response bodies and their impact on and presence in guidelines
16:34:28 <cdent> notmyname had some comments on https://review.openstack.org/#/c/322194/ and other recent guidelines about non-json or non-small apis
16:34:48 <cdent> most of our guidelines make fine sense in the json world, but not so much elsewhere
16:35:00 <cdent> are we mostly focused on the json-api arena?
16:35:05 <elmiko> hey
16:35:12 <elmiko> sorry, missed my calendar bing
16:35:50 <cdent> your penance is being the primary on the newsletter this week
16:35:56 <elmiko> haha
16:37:52 <cdent> I tend to think that we should focus on good behavior in headers and http and what not in general, and when thinking about bodies, mostly concern ourselves with JSON as everything else is often an edge case
16:38:07 <etoews> agreed
16:38:26 <etoews> what you described covers 98% of openstack apis
16:38:34 <cdent> elmiko: ?
16:38:54 <elmiko> that seems like a reasonable statement on the face, what's the context?
16:39:18 <elmiko> like, what non-json apis are we talking about?
16:39:26 <etoews> i'm fine with swift being an exception but we can't constantly have to call out that it's an exception in every single guideline
16:39:29 <cdent> recent comments from notmyname on https://review.openstack.org/#/c/322194/ and other recent guidelines
16:40:09 <cdent> I would guess that he's wary of being called out as non-normal at some point down the road, just for swift doing what swift does.
16:40:27 <cdent> so there's some desire to make it explicit
16:40:31 <cdent> to avoid future drama
16:40:33 <cdent> but I'm guessing
16:41:04 <elmiko> is this mainly about apis returning multi-part binaries and stuff?
16:41:27 <etoews> that would be fine with me but let's call it out as a high level exception somewhere "non-json apis are okay but are out of scope of these guidelines"
16:41:46 <elmiko> etoews++
16:41:55 <etoews> instead of littering the guidelines with exceptions
16:42:08 <cdent> yes
16:42:15 * cdent makes a bug
16:44:52 <cdent> okay, moving on
16:45:06 <cdent> #topic open mic
16:45:23 * elmiko beat boxes
16:45:26 <cdent> anything else new business-wise. good stuff from rosmaita. anyone else?
16:46:06 <cdent> (aforementioned bug:
16:46:09 <cdent> #link https://bugs.launchpad.net/openstack-api-wg/+bug/1614624
16:46:09 <openstack> Launchpad bug 1614624 in openstack-api-wg "top level caveat about json focus required" [Undecided,New]
16:46:10 <cdent> )
16:46:23 <cdent> no new biz
16:46:33 <cdent> #topic guidelines
16:46:39 <cdent> #link https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
16:46:57 <cdent> I was gonna say my uri thing was ready to merge, but etoews has made a reasonable request for moar hypertext
16:48:32 <cdent> there's a non-voting comment on https://review.openstack.org/#/c/354266/ that I'm not sure I'm fully parsing
16:48:44 * etoews ruins all the fun
16:49:14 <etoews> i think i understand that comment
16:50:09 <etoews> qiming would rather see an example with something like href="/servers/1234"
16:50:27 <elmiko> that's what it sounds like
16:50:53 <cdent> I suppose that would be more aux context?
16:51:00 <etoews> that puts the onus on the client to construct the full URI
16:52:29 <cdent> 8 minutes left
16:52:49 <cdent> are the other two guidelines ready for freeze or need more discussion?
16:54:36 <cdent> i'd say no on https://review.openstack.org/#/c/346846/ (just my vote)
16:54:43 <cdent> and yes on https://review.openstack.org/#/c/353396/ (many votes)
16:56:18 <elmiko> i concur
16:56:22 <elmiko> also added my reviews on those
16:56:42 <etoews> agreed
16:57:05 * cdent sends hassle
16:57:27 <etoews> :)
16:58:50 <cdent> okay, two minutes
16:58:53 <cdent> newsletter
16:59:03 <cdent> #topic weekly newsletter
16:59:08 <cdent> #link https://etherpad.openstack.org/p/api-wg-newsletter
17:00:05 <cdent> I've added the frozen guideline link
17:00:08 <cdent> #endmeeting