16:00:14 #startmeeting api_wg 16:00:15 #chairs cdent edleafe elmiko 16:00:15 Meeting started Thu Apr 6 16:00:14 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 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 16:00:18 The meeting name has been set to 'api_wg' 16:00:19 o/ 16:00:23 \o 16:00:25 hi 16:00:32 #link agenda https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda 16:00:44 #link last meeting http://eavesdrop.openstack.org/meetings/api_wg/2017/api_wg.2017-03-30-16.00.html 16:00:46 we may have a few saharans join us 16:00:52 o/ 16:01:05 #topic action items 16:01:14 elmiko: you were going to make an agenda item about what we do 16:01:20 i'm just doing a drive-by, want to thank cdent for looking over and comenting on some glance specs 16:01:37 cdent: doh, did i miss that? 16:01:48 rosmaita: my pleasure 16:02:13 sorry, i totally missed that 16:02:36 elmiko: if I recall correctly it was in response to suggestions that our job is guidelines, whereas I was asserting that we do other stuff that happens to result in guidelines 16:02:52 we can punt that until next time or even the summit? 16:03:00 cdent: that sounds familiar, thanks for jarring the dust 16:03:09 i'm ok with that 16:03:12 #action elmiko to continue thinking about how to discuss and formulate what we do 16:03:16 it seems like a perfect topic *for* summit 16:03:22 that was the only action item 16:03:35 #topic new biz 16:04:12 it turns out that due to the good graces of the foundation, elmiko and I will be at summit and there will be at least one session (in the usual roundup sense, but with a focus on the interoperability debate) 16:04:17 edleafe: are you still a no? 16:04:28 yeah, that's not going to change 16:04:34 =( 16:05:17 depending on how our conversations here go about the purview of the wg, i think we should have an agenda item at summit to discuss it too 16:05:20 are we happy with just one session and a strong presence elsewhere, or should we book a second session (we're allowed up to two) 16:05:37 one on interop, one on the wg scope? 16:05:40 s/summit/forum/ right? 16:05:53 is that what it's called now? 16:06:06 dtantsur: heh, yeah, sorry, habit. 16:06:08 we have forums and PTGs :) 16:06:18 ahh, cool. thanks for that dtantsur 16:06:19 elmiko: it's forum for the interact with people bits 16:06:30 the expo is still the summit? 16:06:43 the overarching thing is still summit 16:06:52 * dtantsur reminds that people can already start planning for the PTG 16:07:12 and the ptg is only 3 months away? 16:07:17 september 16:07:56 #action elmiko and cdent to decide (with input from everyone) about how to do summit 16:08:17 #topic sarah and microversions 16:08:25 tosky and tellesnobrega ? 16:08:34 sahara* :) 16:08:44 aw, that's habit too, it's my wife's name :) 16:08:52 muscle memory 16:09:04 hi, the long standing work to Sahara API v2 is finally moving 16:09:12 but I suspect she is not too concerned with microversions (except listening to me curse about them) 16:09:12 Your wife is in the Big Tent? 16:09:12 hehe 16:09:30 (work formalized by elmiko some time ago) 16:09:40 progress \o/ 16:09:46 so one of the questions was how to use microversioning; speaking with elmiko the impression is that, until we declare the API as stable, 16:09:50 cdent: indeed! 16:09:55 * dtantsur has hard time writing "Iron" without ending up with "Ironic" (and I made this mistake in this sentence too!) 16:09:59 we don't really need microversioning, as we can tune it on the way slightly 16:10:20 and that the microversioning part, if needed, would start after stabilizing the API 16:10:26 tosky, what's your definition of "stable" here? 16:10:38 dtantsur: there is an official definition, iirc 16:10:51 tosky there are a lot of different perspectives on that and it depends quite a bit on whether you consider yourself a CD project 16:10:58 there are many, I suspect, I wonder which one you use ;) 16:11:01 i was taking "stable" to mean when the sahara team actually released it as official to users 16:11:16 uh 16:11:29 elmiko, I suspect it's not a common definition (though I like it) 16:11:41 dtantsur: yeah, i could be off in left field here 16:11:42 what are the possible states for an API? Only STABLE and DEPRECATED? 16:11:51 If sahara does not consider it self continuously deployed, then until there is a release (at the end of the cycle) then while building the API versions can be a hassle 16:12:00 i thought we had EXPERIMENTAL too 16:12:40 elmiko, we should, at least 16:12:42 cdent++ 16:12:52 maybe we need to adjust that guideline 16:13:17 * dtantsur wonders if wording like "EXPERIMENTAL" or "UNSTABLE" may frighten people 16:13:26 dtantsur: they should! 16:13:36 the microversions guidelines which describes version states is explicitly for microversions and makes the assumption that the thing, whatever it is, is already released 16:13:40 probably you're right, yes :) 16:13:49 if you use something EXPERIMENTAL or UNSTABLE, you are on your own (Debian teached that for decades) 16:13:50 :) 16:13:57 tosky++ 16:14:05 i totally agree, people should take notice at those terms 16:14:06 ok, so let's go back 16:14:16 tosky: the trouble with that for an API is that seeing that experimental-ness is not always assured 16:14:27 cdent: well, I mean 16:14:34 tosky: https://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html?highlight=experimental#version-discovery 16:14:50 caveat emptor 16:14:50 from http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html , the statuses are CURRENT, SUPPORTED, DEPRECATED, and EXPERIMENTAL 16:14:59 edleafe: jinx! 16:14:59 from all my experience, if people want something in production, they'll use it no matter what and complain if you break it 16:15:10 dtantsur: we will not enable it by default 16:15:21 I'm pretty sure we are not big enough for people to start using it 16:15:29 you bet :) 16:15:30 yeah, i agree tosky 16:15:41 and well, about using new API and switching to them, we have many examples were we can't kill the old APIs :) 16:15:47 this is a good problem to study with sahara as a pattern for other projects given its size 16:15:47 tosky: can we role back to whatever the original question is? What are you trying to decide? 16:15:55 roll 16:16:02 so, two things: 16:16:06 dtantsur: true, but at some point we can justify not wasting effort for those cases 16:16:27 edleafe, this is also true, yeah 16:16:29 - EXPERIMENTAL state, then CURRENT/SUPPORTED and only at that point we can really need microversioning, correct? 16:16:41 but now I have a more personal question 16:17:04 about microversioning, as I'm not one of the people exactly happy about microversioning as it stands 16:17:15 tosky: you should lay the groundwork for microversions ASAP, but you would never worry about bumping an experiemental version 16:17:24 agreed with edleafe 16:17:56 agreed with elmiko agreeing with edleafe 16:18:02 XD 16:18:07 edleafe: just to clarify: do we need to bump the version even experimental APIs? 16:18:11 agreed with anyone agreeing with me 16:18:22 if it's experimental, I thought that it can break anytime 16:18:34 tosky: no, no need to bump experimental 16:18:35 tosky, my understanding is "no". just make sure you provide the correct information in the root and /v{MAJOR} endpoints 16:18:36 tosky: no, that's what he's trying to say: put in the infrastructure for handling microversions but don't bump the version 16:18:38 tosky: no - experiemental is the equivalent of alpha software 16:18:53 once it is not experimental, then you start bumping 16:18:53 tosky, i.e. when I started ironic-inspector, I did not think about it, and we had to fix / as we went 16:19:02 ok, we are on the same page - sorry for asking again 16:19:07 * dtantsur did not think about many useful things back then, to be fair 16:19:09 tosky: no worries 16:19:09 back to microversioning in general 16:19:36 tosky: i said something similar in the sahara meeting, you should lay the foundation for microversions now, but don't do anything to advance them until the api is released as current/supported 16:19:55 right now the microversioning allows you to create incompatible changes, which are hidden until you request that specific microversion 16:20:25 pretty much, yes 16:20:32 *any* changes are hidden, modulo maybe critical bug fixes 16:20:47 what I would like to try to implement for Sahara (but I'm only a QA, so it's not up to me too), given that we have time to stabilize it, is to try to use microversioning with non-breaking changes 16:21:04 more or less the equivalent of "keep the ABI" in C/C++ world 16:21:14 tosky: any change is considered "breaking" in microversion land 16:21:15 that's pretty much how it's intended, already 16:21:36 make any change, new version 16:22:05 this is how it is now 16:22:44 but let's say we implement it in a way to keep always a theretical compatibility with old clients 16:22:48 tosky, actually, we do it for ironic-inspector (more or less historically, but I doubt anyone cares enough to change it). 16:23:02 I still prefer it to the official api-wg way, but I'm badly outnumbered in it 16:23:13 for example introducing only changes which do not change the signature of methods, or only add new parameters in the end with default values 16:23:45 tosky: are we talking code methods, or API methods? 16:23:56 doing that is good behavior, but if you're doing microversions, those types of changes are still another microversion 16:23:58 API methods 16:24:03 yes, it is 16:24:20 but would it be possible to have a recognition, going forward, for this kind of practice? 16:24:36 I'm not suggesting to change anything for people who want to use microversioning as they are now 16:24:50 I'm just asking for the possibility to recognize this behavior going forward 16:24:58 tosky: I think mordred is thinking about something along those lines 16:25:16 imo, i see this as a social contract at the project level and it sounds like tosky would like something in the guidelines acknowledging this behavior. is that accurate tosky? 16:25:17 with a "never breaks compatibility" tag of some kind 16:25:24 yeah, that's the idea 16:25:44 no one harmed, just something more for people who want to try to be more... conservative 16:25:45 I think in the guidelines is the wrong place, as we get combinatorial explosions of explanation in the guidance 16:25:51 i like the "never breaks compat." tag, that speaks volumes to the work the team is doing 16:25:55 but a tag that a project could assert would be nice 16:26:06 agreed 16:26:17 from my QA point of view, keeping the compatibility is a bit more costly when you plan it, but it reduces the test matrix 16:26:25 which I really want to keep simple :) 16:26:33 Most people are assuming this when talking about "nnon-breaking" changes: https://martinfowler.com/bliki/TolerantReader.html 16:26:57 here's the tag: 16:27:03 as I said, my background is more this: https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B 16:27:03 That doesn't cover multi-cloud interoperability, though 16:27:07 #link never break compat: https://review.openstack.org/#/c/446561/ 16:27:40 #link Tolerant reader https://martinfowler.com/bliki/TolerantReader.html 16:28:33 that spec seems exactly what I was thinking 16:28:35 interesting 16:28:54 tosky: I'd recommend you comment on there if you'd like to see such a thing exist 16:29:01 oh, sure 16:29:02 there was some discussion at a TC meeting but the reaction was mixed 16:29:19 but why? It does not take away anything for people who don't want to implement it 16:29:22 I see it as something more 16:29:36 welcome to governance? 16:29:36 there was concern that it was hard to intepret 16:29:55 playing devil's advocate a bit: too many ways to version API make it harder to consume various services via some common code 16:30:17 dtantsur: don't think tosky is really talking about versioning here, something next to it 16:30:45 Yeah, this is the "till death do us part" mindset to APIs 16:30:52 versioning come close, but technically with such rules implemented, a client for x.y would work with any future x.y+n 16:31:11 if it could ask for that x.y+n 16:32:02 playing devil's advocate again: a badly written client can break on new fields introduced in a response 16:32:08 (I've seen such examples) 16:32:38 but that's a bug in the client 16:33:04 Not all agree that the problem is the client 16:33:12 ideally, wouldn't the client be requesting x.y? 16:33:20 it depends on how much you are clear on your rules 16:33:30 Adding a field to a response means a client can't use a "for each" pattern in processing the response 16:33:47 i mean, once you introduce microversions, won't all clients need to use them or default to the minimum version provided? 16:34:03 i thought there was guidance on this 16:34:05 right, but if you say it from the beginning (you will get *at least* fields), you should plan accordingly 16:34:05 (or default to latest and run with fire) 16:34:24 cdent: yeah, one or the other, i can't remember what the guide saysa 16:34:48 elmiko: yes, with microversioning that's the case; I was talking about the technical possibility if you use stricter rules 16:34:57 tosky: i'm not following how this would be possible, if you release v2 with microversions then by definition all sahara v2 clients will need to use them 16:35:00 elmiko: and (possible) evolution for people using this in a far future :) 16:35:02 tosky: it would be nice if the world was like that, but when you say "you say it" who is listening? can you guarantee people will listen? no. do you still want to be useful and usable 16:35:17 elmiko: the whole point of microversions is you don't get a changed response unless you specifically ask for it 16:35:29 edleafe: right 16:35:37 cdent: but if you start from this point, then we can close everything and go work on agriculture 16:35:47 which is why i'm stumped how a client expecting x.y would choke on x.y+1, it should never request x.y+1 16:36:37 tosky: I totally hear what you are saying. It is an argument I have made myself. But there's been a lot of discussion which has ended up being pretty resigned to the fact that we should make the HTTP APIs robust in the face of people not paying attention. 16:36:52 heh 16:37:19 elmiko, this is all, however, assuming that no abstractions are leaky 16:37:20 cdent: that's fine; that's why having at least recognition about this tag could help at least, even if there is microversioning 16:37:28 which hides the strictness implemented 16:37:39 if you have abstractions leaking so heavily as Ironic's ones, it can never be strictly implemented 16:37:57 tosky: Yeah, I think you're right. I think doing both microversions and what you are describing (in some form) is a good thing. Overall we want to minimize changes to APIs once they are published. 16:37:57 so don't implement it :) 16:38:12 dtantsur: well, in that case, no versioning approach will work 16:38:19 and then, in few years, we can discuss again wheater we can allow a "free for all" for strict clients :) 16:38:21 dtantsur: good point 16:38:27 tosky: and of course you are always welcome to not do microversions, or put off using them for a long time 16:38:45 I think it is fine to take a long time to stabilize an API 16:38:52 edleafe, s/work/be perfect/ 16:39:01 even leaky abstractions can be useful ;) 16:39:06 i think that's a strong point cdent , especially for sahara 16:39:12 (but that's my personal opinion, not official guidance, etc) 16:39:19 dtantsur: "work" in the sense of keeping every consumer happy 16:39:35 does the complexity of microversions really buy anything for the sahara project, i tend to think no 16:39:39 cdent: that's my hope; the API has been redesigned from scratch, it is taking some time, I hope that version bumps won't really be needed 16:40:03 cdent: that's my opinion, too 16:40:04 well, i layed the foundation, so of course it won't need changing! /s 16:40:11 https://blog.leafe.com/api-longevity/ 16:40:14 * cdent proposes we rename the group from api-wg to microversion-support-group 16:40:22 LOL 16:40:22 * dtantsur +1 16:40:25 :D 16:40:43 cdent: maybe that should be our second session at the forum ;) 16:40:53 cdent: nah. MSG will always be Madison Square Garden to this New Yorker 16:40:55 i'll bring the tissue 16:41:09 typical new yorker, thinks they are the center of the universe ;) 16:41:14 hahaha 16:41:28 I think it's all from me for this point, at least for now (and probably for the next two or three cycles :) 16:41:29 thanks 16:41:35 * edleafe notes that we actually *are* the universe 16:42:06 tosky: feel free to post the mailing list with questions and comments and what not as you progress. I think having more conversation in email about this stuff would draw out lots of ideas 16:42:30 my only other open biz topic is that I renamed the compability guideline to interoperability because I felt like that was how it had to go: 16:42:35 cdent: +1 16:42:37 #link interop: https://review.openstack.org/#/c/421846/ 16:42:48 +1 on the name change 16:42:49 yep, at least for this cycle we will mostly work on the EXPERIMENTAL side 16:42:59 we need to bring that one to a close and perhaps also start a new one for the issue that edleafe brought up 16:43:09 but we need some completion/closure/motion 16:43:45 if the people here can review it, yet again, maybe by next week we can freeze it 16:44:21 ack, added to my queue 16:44:25 * dtantsur too 16:44:46 thanks 16:44:55 #topic guidelines 16:45:00 #link https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z 16:45:38 looks like everything needs either more review, or tuning 16:45:48 the http tags thing is close, but hasn't actually had that many eyes on it 16:46:25 anyone want to highlight an issue with a guideline? 16:46:48 #topic bug review 16:46:54 #link https://bugs.launchpad.net/openstack-api-wg 16:46:54 The pagination issue you commented on 16:46:59 no new bugs 16:47:01 wow, you're too fast 16:47:18 edleafe: see, I have expectations about your typing. I've been primed 16:47:33 oh the 400 or 404 thing on pagination, yeah. your thoughts? 16:47:38 Well, to be fair, I was looking at the tags first 16:47:52 On 400 vs. 404, neither is correct 16:48:00 we have to decide which is less wrong 16:48:10 404 is more wrong because of why I said :) 16:48:19 and 400 is the fallback when nothing else seems to fit 16:48:58 Well, I'd appreciate some others to act as tie-breakers 16:48:58 in case it is not clear we are back on 16:49:01 technically it is a client side error 16:49:02 #topic guidlines 16:49:07 #undo 16:49:08 Removing item from minutes: #topic guidlines 16:49:13 #topic guidelines 16:50:27 #link pagination guideline https://review.openstack.org/#/c/446716/ 16:50:56 anyone else besides elmiko want to weigh in? 16:51:13 * dtantsur will, but he did not read yet 16:51:19 yeah, guess i'm in the 400 camp now 16:51:21 cool, thanks 16:51:42 elmiko: all 4xx are client-side errors 16:51:49 400 is simply the fallback 16:52:03 edleafe: right, it just seemed like there was no more specific error 16:52:29 i mean, i can understand the 404 argument, but i like the way cdent stated it in his comments on the review 16:52:43 "there is no specific error" is a typical problem with HTTP API 16:52:51 sadly, yes 16:53:19 I can tell you horror stories about 409 Conflict in Ironic :) 16:53:23 I'll respond to cdent on the review 16:53:39 dtantsur: we've got those in placement too, but there's a plan to start using the errors guideline to address it 16:53:42 i was just stating the obvious that since its a client side error and there is nothing more specific that 400 was probably the best 16:54:24 "410 Gone 16:54:25 Indicates that the resource requested is no longer available and will not be available again. " 16:54:30 (yes, I know that you want to kill me now :) 16:54:34 LOL 16:54:48 definitely not 410, that means something very specific: never ever try this URI again 16:54:53 but to cdent's point, the resource (the collection) *is* still there 16:55:04 five minute warning 16:55:09 my only problem with 400 is that it's hard to distinguish from other bad requests 16:55:19 that's why we have the error guideline! 16:55:22 \o/ 16:55:26 so e.g. on receiving a 404, a client could try to re-get the marker 16:55:34 or just start from the beginning of the collection 16:55:40 with 400 it's probably doomed to just fail 16:55:52 I think in this case, no matter what the response code, there's going to need to be special handling 16:55:58 ah, i see, you're talking about programmatically resolving the error 16:56:01 no? 16:56:02 elmiko, yep 16:56:04 dtantsur: or re-request the previous page, which should now have a new marker 16:56:07 cdent: i agree 16:56:28 in which case 400, because 404 already has clear meaning: this uri is not found 16:56:33 and that will be misleading in many ways 16:56:42 with just 400 you never know if the request is broken or what 16:57:00 dtantsur: that's why the error message is super-critical 16:57:01 yes, but that's the true case in this case: something went wrong, but it's non obvious 16:57:04 yeah, i can see how this is going to be tough to resolve 16:57:12 edleafe, assuming you want clients to parse them 16:57:17 cdent, my definition of "this uri is not found" allows this actually 16:57:32 we are discussing an edge case of an edge case, just for perspective 16:57:38 dtantsur: to play devil's advocate (which you seem to enjoy ;) ), how will your client know that the pagination request had a bad marker and the whole URI was bad though? 16:57:45 dtantsur: strictly speaking, yes, because the query param is part of the uri, but from a human standpoint, people don't think like that 16:58:03 2 minute warning 16:58:12 given that, I think we should punt this fun discussion to the review 16:58:16 Humans?? Where did they come into the discussion?? 16:58:17 cdent, many do, but I see your point 16:58:17 fair 16:58:21 edleafe: LOL 16:58:33 yeah, I'll think about it til tomorrow morning, I'm not the brightest thinker at 7pm 16:58:44 edleafe: I don't know, for that, you might have to do the newsletter 16:58:52 haha 16:59:29 * edleafe proposes changing our name to the Human Programming Interface Working Group 16:59:41 i could do the newsletter, but it won't go out for a few hours, i have solid meetings till about 4 16:59:42 (but if you haven't got the cycles I will, but need to go have a cup of tea and a sit down in the sun outside) 16:59:49 (first) 16:59:52 edleafe: LOL, love it! 17:00:10 edleafe++ 17:00:11 I'm kinda booked for the next 2 hours 17:00:18 okay I'll do it 17:00:22 thanks everyone! 17:00:25 #endmeeting