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