16:00:13 <etoews> #startmeeting api wg
16:00:14 <openstack> Meeting started Thu Jan 29 16:00:13 2015 UTC and is due to finish in 60 minutes.  The chair is etoews. 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:18 <openstack> The meeting name has been set to 'api_wg'
16:00:28 <etoews> hi all!
16:00:31 <elmiko> hello/
16:00:34 <salv-orlando> aloha
16:00:37 <cdent> hola
16:00:39 <kaufer> hello!
16:01:22 <etoews> 1 sec
16:02:42 <etoews> #topic agenda
16:02:48 <etoews> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
16:02:57 <edleafe> o/
16:03:11 <etoews> so we have a few topics i'd like to focus on this meeting rather than our usual agenda
16:03:26 <etoews> let's tackle the specs question first
16:03:33 <etoews> #topic openstack-specs
16:03:56 <etoews> i attended the cross-project meeting on tues. sigmavirus24 was there too.
16:04:28 <etoews> the api wg is basically looking for more visibility for reviewing our guidelines
16:04:49 <etoews> ttx had an interesting suggestion for us
16:05:33 <etoews> to quote ttx from an email to openstack-dev "keep the api-wg repository for the
16:05:33 <etoews> various drafting stages, and move to openstack-specs when it's ready to
16:05:33 <etoews> be "recommended" and request wider community comments. Think Draft and
16:05:33 <etoews> RFC stages in the IETF process :)"
16:06:01 <etoews> there's been some further conversation on the ml about this
16:06:14 <etoews> has everybody had a chance to read the ml thread?
16:06:27 <etoews> take a minute to do so and let me know what you think
16:06:33 * elmiko rushes off to email
16:07:26 <sigmavirus24> #link http://lists.openstack.org/pipermail/openstack-dev/2015-January/055443.html
16:07:30 <sigmavirus24> elmiko: ^
16:07:32 <kaufer> I've read the ML replies, I share the same concerns as Sean about having multiple repos
16:07:47 <edleafe> same here
16:08:04 <sigmavirus24> Yeah, I noticed just this week that a bunch of cross-project drivers started reviewing and -1'ing some of our proposals
16:08:08 <elmiko> sigmavirus24: thanks!
16:08:23 <cdent> I think the visibility of new recommendations is a bigger deal than the repo aspect
16:08:28 <sigmavirus24> Humorous to me that everyone agreed to a separate repository though in the beginning and now wants it unified in one place
16:08:36 <elmiko> i'm +1 for single repo, but i like the idea of separating the drafts from the guidelines
16:08:42 <cdent> It's not clear that gerrit is really working as a place to discuss...
16:08:54 <cdent> (discuss the drafts I mean)
16:09:23 <etoews> cdent: how else would such discussion happen?
16:09:37 <elmiko> i think we should create a template like is used for the project spec repos, and then have the discussions through the patches to the repo. very similiar to project specs now.
16:09:54 <ryansb> also the merged/unmerged distinction is a great approved/draft distinction
16:10:02 <sigmavirus24> So I think there are also some serious misconceptions around the documents the API-WG is producing as well that seem to continue to pop up
16:10:03 <edleafe> cdent: that's pretty much how all other specs are discussed
16:10:03 <elmiko> ryansb: +1
16:10:12 <sigmavirus24> == ryansb
16:10:13 <etoews> for reference
16:10:15 <etoews> #link https://github.com/openstack/openstack-specs
16:10:21 <etoews> #link https://github.com/openstack/openstack-specs/blob/master/template.rst
16:10:29 <cdent> for sake of visibility I think email would be better. But basically I'm -1 on any non-code review happening in gerrit, so I'm probably just a grape in the path of progress.
16:10:51 <elmiko> etoews: i think we will need to customize the template, but details...
16:11:31 <etoews> so i'm +1 for single repo too
16:11:32 <elmiko> cdent: ack, but doesn't that go against the grain of how we review specs now? (for non-api-wg projects)
16:12:44 <etoews> who is +1 for single repo?
16:12:48 <elmiko> +1
16:12:50 <kaufer> +1
16:13:16 <sigmavirus24> +1
16:13:22 <sigmavirus24> etoews: #vote maybe?
16:13:27 <dtroyer> +1
16:13:35 <sigmavirus24> (so it's in the meeting notes)
16:13:37 <edleafe> +1
16:13:49 <etoews> sigmavirus24: i was thinking just use #agreed
16:14:03 <sigmavirus24> ah, didn't realize that could be used outside a vote :)
16:14:36 <etoews> cdent: ryansb: care to vote?
16:14:40 <cdent> +1
16:15:03 <cdent> elmiko: I think underlying this is that I don't think the api-wg guidelines are the same as specs...
16:15:11 <etoews> i think we've got consensus on that.
16:15:24 <etoews> #agreed the api wg should only use a single repo
16:15:28 <elmiko> cdent: ok, that makes a good deal of sense
16:15:45 <etoews> now the question becomes which repo?
16:16:03 <cdent> elmiko: we keep using both terms guidelines and spec but that's not really the same thing.
16:16:06 <sigmavirus24> etoews: what options do we have outside openstack-specs?
16:16:18 <etoews> the current api-wg repo
16:16:40 <elmiko> cdent: true, although i think the metaphor of specs can be applied to api-wg stuff, but you're correct it's not the same as a code spec.
16:16:49 <etoews> also see #5 of http://specs.openstack.org/openstack/api-wg/process.html
16:17:22 <sigmavirus24> It's not the same definition of spec as is uses by projects but it is in a sense a spec. But I agree we should really avoid confusing language as much as possible
16:17:33 <etoews> if we were to continue on in the api-wg repo, at some point in the future we supposed release an official version.
16:17:50 <etoews> i'm not exactly sure what form that official version would take at this point.
16:18:10 <ryansb> why not just a generated site from all the content in api-wg?
16:18:22 <sigmavirus24> Regardless, having the discussions on the ML has been kind of worthless because people ignore the [api] tag who aren't already interested in the wg cdent
16:18:26 <elmiko> etoews: maybe something like how some projects publish their apis to the spec repos? (eg keystone)
16:18:32 <etoews> sigmavirus24: +1 i avoid the word spec simply because it's already taken in openstack land.
16:18:44 <ryansb> like writing-apis.openstack.org
16:18:46 <etoews> elmiko: link?
16:19:07 <elmiko> etoews: https://github.com/openstack/keystone-specs/tree/master/api
16:19:09 <sigmavirus24> etoews: http://specs.openstack.org/openstack/glance-specs/
16:19:44 <elmiko> so, if we're talking about guidelines as our official output, maybe instead of specs we should talk about guideline proposals?
16:19:50 <etoews> don't we already effectively have that? http://specs.openstack.org/openstack/api-wg/
16:21:01 <etoews> let's bring the discussion back to visibility
16:21:01 <elmiko> etoews: hmm, maybe. i guess i was thinking more about how we contain the proposals and released guidelines in a single repo. perhaps i'm just missing a few details.
16:21:47 <etoews> in the api-wg repo it seems we have to work harder to get review by affected projects.
16:22:01 <etoews> would that be different in the openstack-specs repo?
16:22:09 <cdent> This is the first meeting I've attended, basically because it's bad for my schedule (I'm in a video conference right now too), but the impression I get from the reviews is that much of the interesting discussion happens during this meeting. That is very bad for visibility and diversity of input.
16:22:34 <etoews> simply by virture that it is a blessed repo
16:22:42 <etoews> cdent: i know what you mean.
16:23:20 <sigmavirus24> So I have email notifications for the api-wg repository set-up so I always review the guidelines as they're proposed etc.
16:23:33 <elmiko> same
16:23:47 <etoews> same but i speculate the CPLs don't
16:23:48 <sigmavirus24> I never set up notifications for anything with APIImpact though which was the other part of this group's mission
16:24:17 <etoews> APIImpact seems to be well adopted but there's too much for us to review!
16:24:18 <sigmavirus24> etoews: right, and the thing is, I don't need notifications for everything in openstack-specs, so if we were to work there, would a separate branch be outside the realm of possibility?
16:24:24 <elmiko> etoews: probably true, but isn't that what the liasons are supposed to be for =)
16:24:51 <etoews> and not many merged guidelines to reveiw against
16:25:20 <sigmavirus24> I also find it hard to believe that there would be more constructive review of our guidelines on openstack-specs rather than what we're seeing now which is a bunch of -1s because the proposed guideline is too radically different from the current state of affairs
16:25:42 <sigmavirus24> Which stems from people thinking that they'll be expected to immediately implement these changes because they never followed the ML threads about proposing how to upgrade
16:25:43 <etoews> sigmavirus24: i don't think number of email notifications should be a driver for this decision
16:26:09 <sigmavirus24> etoews: but there is a difference between overall specs (logging, etc.) and the guidelines we're proposing
16:26:15 <etoews> sigmavirus24: true
16:26:18 <sigmavirus24> having them on the same branch will probably overload more than just us
16:26:23 <elmiko> i think it's a good point about watching a repo and wanting to filter only some of the content there
16:26:48 <etoews> we would need a subsection or branch or something if we were in openstack-specs
16:26:59 <sigmavirus24> We don't currently have a lot of proposals or other information generated from ours, but we could quickly add a lot more volume up on openstack-specs which will undoubtedly annoy people
16:27:07 <elmiko> i'd like to think it would make it easier for participation if it's contained in a separate api-wg repo
16:27:11 <sigmavirus24> etoews: yeah, that's more my point
16:27:33 <etoews> there must be other text we could filter on to only see specs relevant to us
16:27:59 <cdent> I think that its own repo is more likely to enable efficient discussion, but at the cost of visibility.
16:28:18 <cdent> I think we can probably figure out how to deal with visibility in some other way.
16:28:33 <etoews> cdent: that's the tradeoff i see
16:28:59 <cdent> (such as making explicit invitations to certain reviews on the mailing list, more often)
16:29:36 <etoews> basically do a better job of reaching out and pulling in relevant reviewers.
16:29:52 <sigmavirus24> cdent: I think you overestimate the usefulness of asking for review on a high-traffic list like -dev because even then I've seen little participation from the people whose feedback we seek the most
16:29:52 <cdent> yes
16:29:55 <elmiko> would it be possible to have the api-wg as a submodule of openstack-specs?
16:30:07 <sigmavirus24> It seems most efficient to find people on irc and ping them directly
16:30:37 <sigmavirus24> elmiko: I'm not sure it would track well and I don't think it would contribute to visibility. We'd also need a bot to update the submodule each time a guideline is merged
16:30:40 <etoews> elmiko: i dunno
16:30:43 <cdent> sigmavirus24: I agree that it is likely a fruitless task, but if we want to make the appearance of inclusivity then the mailing list is the only one that transcends membership in cliques and existing in certain time zones
16:30:54 <elmiko> sigmavirus24: ahh, yea. that seems like a lose
16:30:57 <sigmavirus24> And that bot would quickly become more annoying than the OpenStack proposal bot
16:31:00 <etoews> i do know that i'm not crazy about submodules
16:31:10 <sigmavirus24> cdent: the problem is, I don't want the appearance, I want the actuality
16:31:25 <cdent> good luck getting that in openstack sigmavirus24 :)
16:31:29 <edleafe> :q
16:31:32 <edleafe> ugh
16:31:38 <sigmavirus24> edleafe: we are not vim. we are emacs ;)
16:31:44 <elmiko> uh-oh...
16:31:50 <edleafe> sigmavirus24: wash your mouth out!
16:31:53 <edleafe> :)
16:32:00 * sigmavirus24 uses both in reality =P
16:32:24 <sigmavirus24> Okay we're half-way through, should we move on to other topics?
16:33:03 <etoews> maybe...
16:33:09 <dtroyer> last thought: keep in mind that this group is still relatively young, it takes some time to build the awareness of what we're doing
16:33:19 <cdent> dtroyer++
16:33:33 <cdent> there's definitely been an upswing in participation from "others" in the very recent past
16:33:37 <elmiko> dtroyer: good point
16:34:04 <etoews> dtroyer: good point. i'm highly conscious of that in many respects. what we're doing right now is making early design decisions.
16:34:33 <etoews> we'll likely be stuck with the consequences of these decisions for some time.
16:34:58 <etoews> which makes me cautious. maybe overly cautious...
16:35:08 <etoews> there needs to be action here.
16:35:18 <etoews> continue the discussion on the ml?
16:35:25 <dtroyer> wfm
16:35:33 <ryansb> +1
16:35:34 <cdent> +1
16:36:02 <elmiko> +1
16:36:12 <kaufer> +1
16:36:13 <etoews> #action etoews to kickoff a discussion to continue the question of which repo on the ml
16:36:31 <etoews> #topic swift
16:36:39 <etoews> #link https://review.openstack.org/#/c/141229/
16:36:59 <miguelgrinberg> just in time, it looks
16:37:05 <miguelgrinberg> :)
16:37:28 <etoews> so notmyname had some valid concerns in that review
16:38:03 <etoews> thoughts?
16:38:04 <miguelgrinberg> I have been thinking about the last review form notmyname, it has valid points, but swift has so many differences that I don't see how to combine their needs with the rest
16:38:17 <etoews> that's my feeling too
16:38:34 <etoews> "...with the REST"
16:38:36 <miguelgrinberg> I can think of ways to change swift to accomodate what we are proposing, but they are not going to like it
16:38:47 <etoews> nor would client devs
16:39:09 <miguelgrinberg> it seems this metadata in the headers idea came from aws
16:39:14 <miguelgrinberg> they also do that
16:39:17 <ryansb> yeah, it did
16:39:35 <elmiko> i tend to agree with miguelgrinberg's point about the "metadata" object. on the second point, i think it would be helpful to have an example, i'm a little confused.
16:39:35 <miguelgrinberg> I personally don't like it, but notmyname feels pretty strongly about not changing that
16:39:42 <ryansb> but it actually is a nice solution to the object metadata problems
16:40:06 <cdent> I'm surprised that "we" feel it necessary to formalize metadata handling.
16:40:16 <ryansb> I agree w/ notmyname about not having metadata attrs require another HTTP call
16:40:50 <cdent> Or rather, it's surprising that's high on the list of priorities.
16:41:14 <cdent> also given that swift follows no other rules, why would we require them to follow these?
16:41:21 <elmiko> is John == notmyname?
16:41:26 <miguelgrinberg> cdent: not sure it is high, I think it was me that found high discrepancies between APIs, so I proposed we look at it
16:41:38 <dtroyer> elmiko: yes
16:41:56 <elmiko> dtroyer: ty
16:41:59 <etoews> cdent: i believe it came up when a service (cinder?) decided they needed metadata
16:42:19 * salv-orlando agrees with cdent's point on swift
16:42:30 <etoews> we were hoping to use that as an opportunity to get some consistency
16:42:37 <ryansb> who *doesn't* need metadata
16:43:38 <elmiko> cdent: i'm curious, do you think we shouldn't be attempting to create a guideline for metadata? (or maybe it should be lower prio)
16:43:41 <sigmavirus24> ryansb: the NSA doesn't
16:43:49 <elmiko> lol
16:43:57 <ryansb> yeah, but they sure do want it.
16:43:59 <etoews> cdent: i know what you mean. so one way to deal with this is put an asterix by swift saying they aren't subject to certain guidelines
16:44:08 <miguelgrinberg> I think it is going to be an uphill battle to make APIs consistent, we all tend to resist change
16:44:30 <elmiko> etoews: not sure we need an asterisk, isn't our position that these are guidelines not mandates?
16:44:38 <cdent> elmiko: I think making guidelines for representations is a bit odd. I think it is more important to guide that representations be transported correctly.
16:44:41 <etoews> true
16:44:42 <kaufer> So, IMO, this discussion relates to the purpose of our guidelines.  Are they to force all to adopt (I don't believe so) do they exist to help mold future APIs into a consistent state?
16:44:51 <miguelgrinberg> elmiko: find the discussion I had on the topic with notmyname two days ago on openstack-dev
16:44:53 <cdent> To put it another way we should guide the HTTP headers more than we should guide the bodies.
16:44:57 <edleafe> I think we should try to create a best-practice on metadata, but of course, we can't force swift or anyone else to change to match it
16:45:20 <salv-orlando> edleafe: agreed
16:45:22 <cdent> Things like collection handling is relevant, and things like sorting, sure, but resource design is hard to generalize.
16:45:24 <etoews> kaufer: mold
16:45:28 <elmiko> cdent: thanks, that makes it much clearer and good food for thought.
16:45:31 <elmiko> miguelgrinberg: ack, ty
16:45:57 <ryansb> yeah, but this spec isn't (IMO) quite ready to be a best practice for metadata because it doesn't handle concurrent object+metadata creation
16:46:11 <cdent> kaufer++ I think we should be setting aspirational guidelines
16:46:21 <sigmavirus24> cdent: I'm not sure I agree but I'm also not sure that disagreement is especially relevant righ tnow
16:47:01 <sigmavirus24> ryansb: if I remember correctly we couldn't even reach consensus on play object creation
16:47:12 <etoews> to me this is also tangled up with versioning. seems everytime we propose a guideline that doesn't match a particular service, someone will cry foul.
16:47:18 <miguelgrinberg> ryansb: I did not include it in the spec, but metadata should also be accessible as a field in the resource
16:47:24 <sigmavirus24> I don't think we even came close to discussion concurrent creation of object+metadata
16:47:33 <miguelgrinberg> ryansb: does that satisfy your requirement of setting metdata along with the obj?
16:47:39 <edleafe> etoews: of course - that's to be expected
16:47:41 <sigmavirus24> etoews: that's my instinctual reaction to all of this as well
16:47:50 <dtroyer> etoews: that's when we repeat the mantra and move on
16:47:54 <sigmavirus24> perhaps I should just write a guideline for adoption
16:47:55 <etoews> if we could point them at a versioning strategy that everyone can agree on then we'd have an answer for that
16:48:02 <ryansb> as long as I can use 1 request to create the object and its metadata I'm happy
16:48:04 <miguelgrinberg> etoews: are we planning something to educate teams at the summit?
16:48:09 <dtroyer> getting bogged down in this ever time is not productive
16:48:09 <edleafe> etoews: but that shouldn't stop anyone from saying "this is the preferred way to do it"
16:48:17 <elmiko> miguelgrinberg: that's a cool idea
16:48:18 <ryansb> miguelgrinberg: that would work, definitely include that bit
16:48:19 <sigmavirus24> and try to get more people involved on the ML discussion about moving towards adoption of the guidelines through API versions
16:48:33 <etoews> dtroyer: we should come to an agreement on the mantra
16:48:44 <sigmavirus24> etoews + miguelgrinberg should do a co-presentation at the summit on the API-WG and it's goals
16:48:50 <etoews> miguelgrinberg: i'll definitely be proposing to the design summit
16:48:52 <elmiko> etoews: i'm on the bandwagon with regards to us keeping consistent about creating a set of useful guidelines
16:49:01 <dtroyer> "these are guidelines, not prescriptions.  please, no wagering"
16:49:09 <dtroyer> except maybe for that last part
16:49:12 <elmiko> dtroyer: +1
16:49:15 <miguelgrinberg> so I proposed a session to give my views on the openstack API design
16:49:31 <miguelgrinberg> I was thinking more along the lines of describing what the API-WG does
16:50:04 <miguelgrinberg> happy to propose one on that with others.
16:50:31 <elmiko> miguelgrinberg: +1
16:50:37 <kaufer> miguelgrinberg: +1 ... there seems to be confusion that the "guidelines" are rules that all must adpot instead of best practices that is used to help guide future API developent
16:50:50 <etoews> do we need to come up with an official mantra/mission statement on the ML to make sure everybody gets it?
16:50:55 <elmiko> kaufer: we need to clean that messaging up
16:51:03 <elmiko> etoews: i think so
16:51:04 <miguelgrinberg> kaufer: yeah, and also people worry about not being in compliance with the guidelines
16:51:32 <sigmavirus24> elmiko: the thing is we've been messaging that since the start (as far as I recall) and people misunderstand because they don't have time to read the docs on that
16:51:34 <elmiko> etoews: and that mantra should be clear on the wiki as well
16:51:38 <etoews> yep
16:51:49 <dtroyer> miguelgrinberg: that's a worry we should not remove, but set it at an appropriate level.  we want people to think about it
16:52:04 <miguelgrinberg> I think the ideal would be to get people from all projects actively involved
16:52:21 <elmiko> sigmavirus24: fair, we will always have some that miss the message, i guess we just need to be dilligent
16:52:35 <miguelgrinberg> so we need to sell ourselves to the teams
16:52:45 <elmiko> sigmavirus24: gotta have something catchy ;)
16:53:01 <etoews> #action etoews to start api wg mission statement discussion on the ML
16:53:09 <sigmavirus24> Yeah. I think we should also be tagging our messages as [all] when we want other people's feedback because some may think [api] is specific to the group and they can/should skip it
16:53:11 <miguelgrinberg> I think to some, it seems we come up wtih some arbitrary rules in a vacuum and try to push them into all the projects
16:53:14 <etoews> it would have to be 2-3 sentences max
16:53:21 <elmiko> sigmavirus24: good idea
16:53:47 * sigmavirus24 is guilty of not using [all]
16:53:51 <dtroyer> etoews: 140 chars would be awesome
16:53:53 <elmiko> maybe we need some stickers for summit? help get the message out, WE ARE NOT THE API POLICE!
16:54:09 <etoews> sigmavirus24: ya. i'm starting to get the sense that [api] is a bit cliquey.
16:54:31 <sigmavirus24> etoews: I know I filter by tag and read the ones I care about most first and the rest later if I have time (which is rare)
16:54:33 <miguelgrinberg> REST police sounds better =P
16:54:43 <elmiko> lol yes
16:54:48 <etoews> sigmavirus24: same boat
16:55:00 <elmiko> sigmavirus24: same
16:55:25 <sigmavirus24> miguelgrinberg: RESTful police ++
16:55:31 <etoews> #topic open topics
16:55:34 <sigmavirus24> As long as we're not the HATEOASBI
16:55:41 <elmiko> lol
16:55:44 <etoews> anything else to highlight?
16:56:03 <etoews> i do think a version guideline will be one of the first things we need to come up with
16:56:08 <miguelgrinberg> sigmavirus24: you say that to enrage me, I know it
16:56:23 <etoews> it will help teams know there is a path forward
16:56:31 <elmiko> etoews: agreed
16:56:50 <miguelgrinberg> clear steps for projects that have implementations not blessed by the API-WG would be helpful
16:57:07 <sigmavirus24> so silly idea: what if we have a proposed and finalized subdirectory for stuff?
16:57:14 <etoews> elmiko: btw, did you see the email from max lincoln about swagger for openstack projects?
16:57:17 <sigmavirus24> As in stuff is finalized once we have the TC's approval, etc
16:57:24 * notmyname just got online this morning and saw his name
16:57:35 <cdent> miguelgrinberg: is "blessing" the business this group is in? ;)
16:57:43 <etoews> notmyname: 3 minutes to go!
16:57:46 <elmiko> etoews: yes, i need to reply
16:57:47 <notmyname> :-)
16:57:49 <etoews> :)
16:57:59 <elmiko> sigmavirus24: i'm not a fan of that style
16:58:00 <miguelgrinberg> cdent: there you go, it should be clear what we do
16:58:07 <notmyname> etoews: I'd be happy to pick it up in a different channel
16:58:09 <kaufer> sigmavirus24: wouldn't 'proposed' be things under review in gerrit and 'finalizaed' be what is merged?
16:58:21 <sigmavirus24> kaufer: elmiko "silly idea"
16:58:52 <elmiko> sigmavirus24: lol gotcha. we tried something similar in sahara and just refactored it out
16:58:59 <sigmavirus24> A way to get people to not overreact to proposals under going review because we had already described the process as needing approval by the TC once we have some strong set of guidelines anyway
16:59:03 <elmiko> too much work to maintain
16:59:03 <etoews> sigmavirus24: kaufer: under #5 of http://specs.openstack.org/openstack/api-wg/process.html we need to figure out what form "official version" takes
16:59:40 <etoews> but i think that's a ways down the road
17:00:10 <etoews> #endmeeting