16:00:01 <sigmavirus24> #startmeeting api wg
16:00:01 <openstack> Meeting started Thu Feb 26 16:00:01 2015 UTC and is due to finish in 60 minutes.  The chair is sigmavirus24. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:02 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:00:03 <gilliard_> Api-wg ?
16:00:05 <openstack> The meeting name has been set to 'api_wg'
16:00:08 <sigmavirus24> gilliard_: :D
16:00:13 <gilliard_> Ah, yes.  Hello.
16:00:24 <sigmavirus24> Hello everyone!
16:00:28 <dtroyer> o/
16:00:29 <sigmavirus24> #topic agenda
16:00:30 <elmiko> yo/
16:00:37 <sigmavirus24> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
16:00:50 <stevelle> o/
16:00:57 <kaufer> hello
16:01:09 <miguelgrinberg> hi
16:01:33 <sigmavirus24> Moving along
16:01:41 <sigmavirus24> #topic versioning
16:02:12 <sigmavirus24> I think that's etoews' topic, but I wonder if cyeoh is around to talk about it too (seeing as how I think this is related to Nova's versioning)
16:02:37 <miguelgrinberg> there is no proposed guideline on this yet, correct?
16:02:42 <gilliard_> I think it's 4am in Australia
16:03:05 <sigmavirus24> gilliard_: You mean people don't stay up that late for openstack? =P
16:03:14 <gilliard_> Slackers
16:03:21 * sigmavirus24 doesn't know everyone's tz
16:03:27 <sigmavirus24> miguelgrinberg: I don't believe there's one, no
16:04:15 <miguelgrinberg> no, I don't see anything in https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
16:04:22 <sigmavirus24> Should we circle back to this if etoews shows up?
16:04:46 * sigmavirus24 is fairly certain it has to do with microversions in Nova but doesn't know what etoews wanted to say
16:04:54 <sigmavirus24> No dissent so, moving on
16:04:55 <sigmavirus24> #topic previous meeting action items
16:05:01 <sigmavirus24> #link http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-02-12-16.00.log.html
16:05:08 <sigmavirus24> #link http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-02-19-00.00.html
16:05:27 <sigmavirus24> (Since the last meeting was 90% glance, there are action items from the last two meetings there)
16:05:36 <miguelgrinberg> no action items, wow
16:05:53 <kaufer> I had an action to get more input on https://review.openstack.org/#/c/147684/
16:06:12 <kaufer> However, I was hoping to get more consunsus from those in this WG before asking others
16:06:14 <sigmavirus24> kaufer: you got cyeoh's input
16:06:18 <sigmavirus24> ;)
16:06:30 <kaufer> Specifically jaypipes
16:06:42 <kaufer> And you sigmavirus24 :)
16:06:46 <sigmavirus24> Jay isn't around
16:06:51 <sigmavirus24> Uhoh, what'd I do now? =P
16:07:40 <miguelgrinberg> I think it's nice and simple, +1
16:08:10 <sigmavirus24> I haven't read it in a while
16:08:19 * sigmavirus24 will read it after the meeting
16:08:24 <kaufer> I'll send out a note to the ML and then start PM'ing folks on this one
16:08:31 <kaufer> Thanks sigmavirus24
16:08:56 <sigmavirus24> kaufer: sounds good
16:09:03 <sigmavirus24> Other action items people want to update?
16:09:24 <sigmavirus24> #action kaufer to gather more API-WG consensus on https://review.openstack.org/#/c/147684/5 before bringing it to the ML
16:09:54 <sigmavirus24> Onwards then
16:09:58 <sigmavirus24> #topic guidelines
16:10:05 <sigmavirus24> #link https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
16:10:12 <sigmavirus24> #link https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
16:10:24 <sigmavirus24> (in case meetingbot decides to not parse it without stripping the whitespace)
16:10:44 <sigmavirus24> https://review.openstack.org/#/c/155911/ seems to have consensus
16:11:20 <sigmavirus24> https://review.openstack.org/#/c/141229/ needs more input because there's a serious discussion of how to accommodate Swift
16:11:40 <miguelgrinberg> (and that won't be easy)
16:12:24 <sigmavirus24> Well it may not be that we need to accommodate Swift, any more than Swift needs to realize why their current design is ill-considered and why they're currently breaking RFCs and should strive to be incompliance with them
16:12:28 <sigmavirus24> s/incompliance/in compliance/
16:13:03 <miguelgrinberg> sure, or they can opt to not follow the guideline. Nothing will die of it.
16:13:22 <elmiko> sigmavirus24: but tell us what you really think ;)
16:13:27 <miguelgrinberg> they have their reasons, I can understand that
16:13:35 <sigmavirus24> elmiko: heh
16:13:53 <dtroyer> we seem to keep running in to the notion that these guidelines are binding and retroactive
16:14:12 <elmiko> agreed with miguelgrinberg at some level, if swift chooses not to follow the guideline then that is their perogative
16:14:38 <miguelgrinberg> but I think it is a too contrived use case to have influence on this doc
16:15:31 <sigmavirus24> Also if I recall correctly, they're arguing that this would affect object creation for them too, which I don't see how that is the case as this purely affects endpoints for metadata only
16:15:39 <sigmavirus24> Not for creation with metadata
16:15:55 <sigmavirus24> But yes, this is another case of people not understanding that these aren't retroactive guidelines
16:15:59 <miguelgrinberg> yes, this is all about their endpoints, which are too vaguely defined
16:16:07 <miguelgrinberg> there is ambiguity
16:16:23 <sigmavirus24> They're also designed around an API design that iirc Amazon no longer uses
16:16:24 <miguelgrinberg> so a /metadata can be metadata or can be a swift object called metadata
16:16:46 <miguelgrinberg> I have ideas on how to disambiguate, but not sure they want to listen
16:17:08 <sigmavirus24> So discussion should be further focused on that review
16:17:19 <sigmavirus24> Because it appears John and Samuel aren't here
16:17:33 <sigmavirus24> We should probably also involve the ML
16:17:53 <miguelgrinberg> okay, I'll take the action to ask for feedback on the ML
16:18:16 <sigmavirus24> #action miguelgrinberg to get ML feedback on https://review.openstack.org/#/c/141229/
16:18:30 <sigmavirus24> (You can't say I volunteered you for that one miguelgrinberg)
16:18:41 <miguelgrinberg> I did it to myself :)
16:18:54 <sigmavirus24> We also seem to have consensus on https://review.openstack.org/#/c/158179/
16:19:18 <sigmavirus24> But that's less than a week old so we have to wait for more discussion per our own guidelines around merging guidelines
16:19:21 <sigmavirus24> ;)
16:19:33 <elmiko> that one seemed must less controversial too
16:19:38 <elmiko> *much
16:19:44 <cdent> apologies for lateness, had another meeting
16:19:44 <sigmavirus24> elmiko: right
16:19:49 <sigmavirus24> cdent: No worries.
16:21:38 <sigmavirus24> cdent: agenda is https://wiki.openstack.org/wiki/Meetings/API-WG
16:21:44 <sigmavirus24> We're discussing guidelines
16:21:47 <miguelgrinberg> I'm also going to ask for ML feedback on the tagging doc https://review.openstack.org/#/c/155620/
16:22:12 <sigmavirus24> #action miguelgrinberg to bring tagging guideline to the ML https://review.openstack.org/#/c/155620/
16:22:18 <miguelgrinberg> Happy that Heat is implementing this spec :)
16:22:51 <kaufer> miguelgrinberg: Any thoughts on if we need to revisit the repeated query string parameter vs. comma separated that came back up in the tagging guideline?
16:23:09 <kaufer> miguelgrinberg: I thougt that we had closed that issue but it crept back in in that review
16:23:18 <miguelgrinberg> kaufer: don't know. I thought we beat that horse to death, but seems we didn't
16:23:20 <cdent> on the tagging thing: In case it's not clear from the chest inflating going on in the comments there: I'm fine with the spec as is, but we _could_ use tag=foo&tag=bar if we really wanted to
16:23:59 <elmiko> this is also similar to a question i have about filtering
16:24:12 <cdent> I think the reason it came back into play is that there is a large discussion still unresolved about the extent to which we want to be driving global improvement, as opposed to local okayness
16:24:32 <miguelgrinberg> cdent: you could, but it would not be in agreement with the current rev of the guideline
16:24:36 <sigmavirus24> cdent: there's a similar design for sorting that's already been approved and is already being implemented
16:24:50 <stevelle> cdent: conflating what the WG wants and what the community can do?
16:25:19 <sigmavirus24> cdent: the WG can write all the guidelines it wants, the community can do whatever it pleases since we have no real authority
16:25:27 <miguelgrinberg> my view on this is that both options are valid, we have to pick one. We picked single args for sorting, so I think we should stay with single args for everything else.
16:25:42 <cdent> miguelgrinberg: that's reasonable enough
16:25:44 <kaufer> miguelgrinberg: +1
16:26:28 <elmiko> miguelgrinberg: just to be clear, that would be the "tag=foo&tag=bar" foramt?
16:26:31 <miguelgrinberg> elmiko: so that would apply to filtering when we get to it
16:26:48 <miguelgrinberg> elmiko: no, the other one: "tags=foo,bar"
16:27:19 <elmiko> miguelgrinberg: ok, how would filtering look given that approach?
16:27:53 <miguelgrinberg> I haven't look at any implementations of filtering, do you have an example?
16:28:09 <elmiko> https://review.openstack.org/#/c/157563/
16:28:16 <elmiko> that's a spec we're working through in sahara currently
16:28:25 <sigmavirus24> So this has drifted from discussion of the current specs
16:28:29 <sigmavirus24> Should we save this for the end?
16:28:35 <elmiko> i'm cool with that
16:28:39 <miguelgrinberg> yeah, sure
16:28:42 <sigmavirus24> #topic APIImpact
16:28:49 <sigmavirus24> #link https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z
16:28:58 <stevelle> OpenStack has a mess of different filtering models already.  I can get a summary that was cooked up in the py SDK project
16:29:07 <sigmavirus24> There should be a cinder review there that DuncanT was supposed to address here
16:29:13 <elmiko> stevelle: that would be awesome!
16:29:32 <briancurtin> stevelle: https://etherpad.openstack.org/p/find_filters
16:29:37 <sigmavirus24> Oh wait, yuriy_n17 has it at the end of the discussion
16:29:39 <miguelgrinberg> stevelle: +1
16:29:46 <DuncanT> What am I supposed to be addressing, sorry?
16:29:56 <sigmavirus24> DuncanT: https://review.openstack.org/#/c/156552/
16:30:06 <elmiko> briancurtin: thanks
16:30:15 <stevelle> briancurtin: thanks
16:30:15 <sigmavirus24> You and yuriy_n17 were to bring that up during this part of the meeting :)
16:31:04 <DuncanT> Ah, ok. So we discovered today that cinder always uses UTC, except for a couple of migrations
16:31:07 <miguelgrinberg> (I'll save my comments till the end)
16:31:16 <e0ne> sigmavirus24: yes. we want to decide to timezone should be shown in API
16:31:47 <e0ne> as DuncanT mentioned, it isn't big issue for cinder now
16:32:21 <sigmavirus24> I also don't see a blueprint for this in cinder (which would seem to be a good idea)
16:32:42 <e0ne> sigmavirus24: we've got bur reported for it
16:33:06 <sigmavirus24> That would also make it easier for us to discuss because it would more succinctly describe the change being made there
16:33:23 <miguelgrinberg> does this topic deserve a guideline doc? I thought it is pretty standard to use UTC on any public representations
16:33:50 <e0ne> sigmavirus24: do we have any guidelines for it?
16:34:12 <sigmavirus24> e0ne: no there aren't. I mentioned that yesterday during cinder's meeting
16:34:17 <e0ne> sigmavirus24: afaik, nova shows timezone in api, but i could be wrong
16:34:37 <sigmavirus24> My personal taste is to include the timezone information using ISO8601 but I understand that will break current clients
16:34:55 <sigmavirus24> Also any guideline we propose is for future versions of the API, not necessarily for additions to existing versions
16:35:05 <e0ne> if all openstack projects will use utc time in api - it won't be issue at all
16:35:12 <dtroyer> ++
16:35:41 <sigmavirus24> e0ne: agreed. That's basically a de facto best practice for any and all APIs
16:36:07 <e0ne> sigmavirus24: agree. but we must have to document it
16:36:39 <sigmavirus24> e0ne: no doubt. Would you like to write that guideline?
16:36:48 <e0ne> because time to time will got new users and/or developers which rise this question again
16:37:39 <e0ne> sigmavirus24: ok. i'll do it with yuriy_n17. he was an initiator of this topic:)
16:38:30 <sigmavirus24> e0ne: thanks
16:38:44 <sigmavirus24> #action e0ne and yuriy_n17 to write a guideline about datetime representation in APIs
16:38:58 <e0ne> :)
16:38:58 <sigmavirus24> Any other APIImpact reviews people want to highlight?
16:39:00 <stevelle> should be pretty non-controversial
16:39:04 <sigmavirus24> stevelle: I agree
16:39:46 <elmiko> https://review.openstack.org/#/c/157563/
16:39:59 <elmiko> so, we are talking about filtering in our review
16:40:05 <elmiko> and were curious about the most proper methods
16:40:39 <elmiko> the path we are investigating is something like "?filterkey=value&filterkey2=value"
16:41:02 <miguelgrinberg> elmiko: I think that style makes it hard to use negative filtering
16:41:03 <elmiko> or "filterkey=value1&filterkey=value2"
16:41:18 <elmiko> miguelgrinberg: could you elaborate?
16:41:37 <miguelgrinberg> how do you specify that you want anything but a given value for a field?
16:41:40 <sigmavirus24> miguelgrinberg: excluding keys with certain values
16:41:47 <elmiko> we hadn't considered that option
16:41:54 <elmiko> we were only looking at positive filtering
16:41:57 <miguelgrinberg> say you like all servers that are not named "foo"
16:42:17 <elmiko> right, i'm curious what would be a better approach?
16:42:18 <stevelle> ...or all jobs that do not have a tag "foo"
16:42:53 <kaufer> miguelgrinberg: Do you know of any projects that implement negative filtering like that?
16:42:56 <miguelgrinberg> I haven't given a lot of thought, but one possibility is to define a simple query language, and just stuff an expression in a "q" argument
16:43:15 <miguelgrinberg> kaufer: not in openstack afaik
16:43:33 <cdent> I've done things like: select=tag:!foo
16:43:49 <sigmavirus24> cdent: yeah, I think something like that is what miguelgrinberg is proposing
16:44:18 <sigmavirus24> It wouldn't hurt to see if choosing a subset of something people are familiar with (e.g., elasticsearch's query language) would be a good idea *If we need it*
16:44:29 <miguelgrinberg> and then there is the issue of specifying ORs and ANDs
16:44:32 <elmiko> in this case, we mainly need to prune results. i'd really love to look at something i could suggest to the team regarding a query language.
16:45:15 <kaufer> also, there are some projects (ie, nova) where one filter key is filtering using an exact match and another is used using a regular expression
16:45:15 <miguelgrinberg> the gerrit search is an example of a query language, though I'm not sure it has negative filtering
16:45:52 <kaufer> it would be nice if we had a uniform mechanism to define if a filter is an exact match, a regex, a negative filter, etc.
16:45:55 <sigmavirus24> miguelgrinberg: it does
16:45:58 <sigmavirus24> miguelgrinberg: -owner:me
16:46:04 <sigmavirus24> or something like that
16:46:19 <sigmavirus24> it's very similar to elasticsearch's ql
16:46:26 <miguelgrinberg> sigmavirus24: nice, so that's a good model, though it may be too complex for projects that want a simple search
16:46:50 <miguelgrinberg> maybe a guideline should include simple searches as well
16:46:52 <sigmavirus24> right
16:46:55 <elmiko> would there be an issue with something like "?filterkey1=value&filterkey1=-value2"
16:46:58 <elmiko> ?
16:47:10 <sigmavirus24> elmiko: what about val-ue2?
16:47:11 <cdent> there's a lot of overlap between searching, filtering, sorting and limiting
16:47:22 <cdent> but they are also distinct
16:47:24 <sigmavirus24> I would assume it could be done intelligently enough but it might get tricky
16:47:25 <miguelgrinberg> elmiko:  I don't remember who didn't like me proposing the "-" as negative filtering
16:47:43 <sigmavirus24> miguelgrinberg: that was on sort though and was kind of an awkward way of defining asc/desc though
16:47:45 <sigmavirus24> to be fair
16:47:50 <elmiko> hmm, i could see some corner case issues
16:47:55 <sigmavirus24> miguelgrinberg: I think cdent and I were opposed
16:47:55 <kaufer> also, on the topic of filtering ... anyone know if the valid filters for a given project are discoverable?
16:48:13 <cdent> I do not recall that senator.
16:48:15 <sigmavirus24> kaufer: if the project is properly implementing JSON Home it should be
16:48:27 <sigmavirus24> kaufer: also a schema for an endpoint should tell you
16:48:37 <sigmavirus24> I don't expect a project to have globally defined filters for all endpoints
16:48:42 <miguelgrinberg> kaufer: the filters should be the fields in the representation ideally, no need to call them out
16:49:00 <kaufer> so, to align with how we did sort, maybe something like "?filterkey1=value&filterkey1=value2:negative"
16:49:11 <elmiko> kaufer: that's not bad
16:49:21 <miguelgrinberg> kaufer: still no way to specify AND/OR
16:49:31 <kaufer> AND is implicit
16:49:37 <kaufer> but agree, there is no OR
16:49:54 <cdent> want OR, just ask again?
16:50:03 <kaufer> cdent: good point
16:50:05 <miguelgrinberg> I think I'm leaning towards only positive filtering with filterkey=value, and if you want more then define a query language
16:50:19 <stevelle> cdent: costs twice as much to service that way sadly
16:50:29 <elmiko> yea, positive filtering is bog easy with the filterkey=value methodology
16:50:38 <cdent> I wasn't supporting it, just stating the option.
16:50:53 <miguelgrinberg> cdent: that doesn't scale unfortunately
16:51:30 <cdent> if explicit booleans are desired then a quoted query string is probably needed
16:51:49 <miguelgrinberg> cdent: yes, a q=<query> style argument
16:51:53 <elmiko> should we attempt to come up with a standardized query language for the guidelines in addition to the default positive filtering idea?
16:51:53 <cdent> you can have both: simple implict and style queries, plus complex q="some long string of stuff with OR and AND and (* )"
16:51:54 <kaufer> seems like there are a lot of ideas around filtering, should we start an etherpad and use that as a starting point to hash this out?
16:51:56 <cdent> jinx
16:52:01 <sigmavirus24> yeah
16:52:06 <sigmavirus24> We're running close to the end of meeting
16:52:09 * cdent nods
16:52:15 <sigmavirus24> Should we move on?
16:52:18 <elmiko> kaufer: +1
16:52:38 <elmiko> cdent: yea i like the idea of dual approach
16:52:45 <sigmavirus24> Are there other API Impact topics?
16:52:49 <sigmavirus24> It seems gilliard has left
16:53:12 <cdent> I have a what should have been API Impact but couldn't get the commit message changed question/comment:
16:53:24 <sigmavirus24> cdent: shoot
16:54:13 <cdent> Given uri /foo/bar/baz is it legit for /foo/bar to return 404 or should it return _something_ (what?) to indicate that baz (and siblings) might be there.
16:54:25 <cdent> this issue is coming up in:
16:54:45 <cdent> https://review.openstack.org/#/c/159204/
16:55:02 <cdent> (but that's not the place where the lack of APIImpact is, as that's my commit)
16:55:11 <miguelgrinberg> cdent: imo you can return 404
16:55:48 <cdent> certainly from a strictness standpoint 404 is correct, but from a friendliness standpoint, less so
16:56:09 <miguelgrinberg> if you want to return something, then you are getting into the idea of sub-resources
16:56:12 <cdent> It assumes a non human client that already knows the api, rather than a human digging around for kicks and giggles.
16:56:33 <miguelgrinberg> so for example /resource returns a big representation, then /resource/field-name returns a subset of the big resource
16:57:21 <elmiko> so, in the example of /foo/bar/baz, /foo/bar would return all bazs?
16:57:25 <miguelgrinberg> I know people roll their eyes when I say this (I know you are sigmavirus24), but URLs should be opaque, should be discovered, so there is no obligation to have them nicely structured
16:58:06 <cdent> I mostly agree with you miguelgrinberg, if discovery mechanism is present, but when it is not...
16:58:24 <sigmavirus24> elmiko: that's what miguelgrinberg is saying but it may not always be true
16:58:25 <miguelgrinberg> when it is not, you document the valid endpoints, so still not a problem
16:58:37 <sigmavirus24> I'm also not rolling my eyes at you miguelgrinberg, that's a waste without you being able to see it
16:58:42 <cdent> elmiko: baz is one of the bars, /foo/bar would return all the bars
16:58:49 <miguelgrinberg> sigmavirus24: save it for next month :)
16:58:54 <cdent> (or somethign like that)
16:59:06 <elmiko> ok, so the bars might include bazs, amongst other things?
16:59:28 <elmiko> or are bars and bazs unrelated?
17:00:00 <sigmavirus24> we're almost out of time
17:00:07 <sigmavirus24> #endmeeting