16:00:58 <etoews> #startmeeting api wg
16:00:58 <openstack> Meeting started Thu Mar 24 16:00:58 2016 UTC and is due to finish in 60 minutes.  The chair is etoews. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:01:00 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:01:02 <openstack> The meeting name has been set to 'api_wg'
16:01:11 <elmiko> hey =)
16:01:21 <etoews> hello!
16:01:30 <cdent> hola
16:01:57 <etoews> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
16:02:07 <dstanek> hello
16:02:28 <etoews> #topic previous meeting action items
16:02:35 <etoews> #link http://eavesdrop.openstack.org/meetings/api_wg/2016/api_wg.2016-03-10-16.00.html
16:03:00 <etoews> i think we're all checked off there
16:03:12 <cdent> Yeah, a fair stack of stuff got frozen
16:03:34 <elmiko> that was nice
16:03:41 <etoews> very much so
16:04:01 <etoews> #topic Tackling TODOs in existing guidelines
16:04:10 <cdent> ah, this was one I raised
16:04:38 <cdent> I was reading through the existing guidelines and realized there are a lot of blank spots and it made me realize that I don't think much about the guidelines after they pass through gerrit.
16:04:45 <cdent> And we probably need to be more...mindful?
16:04:50 <elmiko> i talked with sdague a little about the TODOs in the error message, i could take a stab at filling those out
16:05:00 <elmiko> cdent: +1
16:05:44 <cdent> Some of them are not aligned with the current scope of the guidelines and hangovers from the earlier wiki pages.
16:06:17 <elmiko> maybe we need to do something like the code-based projects and have an end-of-the-cycle TODO-fest or something?
16:06:19 <annegentle> heh hangovers
16:06:31 <annegentle> hangover cure
16:06:51 <cdent> yeah, end of cycle, get some orange juice, aspirin, coffee, get to work
16:07:04 <elmiko> right, pick a week and do a virtual sprint on the TODOs
16:07:47 <etoews> i suppose it's also a question of how we manage the potential guidelines
16:08:19 <etoews> most projects would use an issue tracker to put TODO stuff into
16:08:31 <etoews> rather than have it in the code (guidelines in the case)
16:08:32 <annegentle> true dat
16:08:32 <elmiko> hmm
16:08:46 <cdent> we could hop on the storyboard bus?
16:09:12 <elmiko> i dunno, i've seen plenty of TODOs stuck in code
16:09:17 <cdent> it might be useful to have some kind of tracking thing in place
16:09:18 <stevelle> that would be an improvement over the current state
16:09:39 <sdague> storyboard is a bus that might not go anywhere unfortunately
16:09:43 <stevelle> only challenge is communicating it is on storyboard
16:09:50 <elmiko> do we need a launchpad for api-wg?
16:09:51 <stevelle> folks wont looks there first
16:09:55 <etoews> i'm not familiar with storyboard beyond it's a thing that was supposed to do project mgmt or something.
16:10:36 <dstanek> if storyboard isn't going to become a thing i think launchpad is good enough
16:10:49 <etoews> ya. it's the simplest possible thing in this case.
16:10:54 <etoews> and our needs are modest.
16:11:22 <cdent> storyboard is newly refreshed. infra is using it more. there was just a posting to the dev list about latest changes and such
16:11:30 <cdent> I was suggesting it merely because of that reminder
16:11:39 <cdent> launchpad is fine too (despite the fact that it is horrible)
16:11:50 * elmiko has not used storyboard
16:11:56 <cdent> it's also prety horrible
16:11:59 <cdent> :D
16:11:59 <elmiko> lol
16:12:06 <elmiko> so.... trello?
16:12:09 <etoews> done
16:12:09 <elmiko> /s
16:12:11 <etoews> :P
16:12:15 <elmiko> haha
16:12:40 <annegentle> heh
16:12:53 <cdent> Can we extract an action from this?
16:12:56 <annegentle> we have openstack-api-site and openstack-doc-tools in launchpad now
16:13:03 <etoews> cdent: we have to
16:13:03 <annegentle> would either of those be useful in this case
16:13:26 <elmiko> seems like lp is the path of least resistance
16:13:30 <cdent> yes
16:13:32 <annegentle> openstack-api-site seems about right
16:13:40 <etoews> cdent: but i would rather do action than extract action
16:13:41 <annegentle> since we were talking about publishing the guidelines there
16:14:01 <cdent> etoews: heh, I was thinking extract the thing we put in an # action
16:14:03 <elmiko> yea, i'm good with api-site, but i think we should get a link up there
16:14:17 <elmiko> (meant to propose a link but it got lost somewhere....)
16:14:48 <cdent> so how about
16:14:50 <annegentle> elmiko: get on it man! :) I'll assign you your first but in openstack-api-site then?
16:14:51 <elmiko> although, i wonder if we shouldn't have a separate lp just for api-wg. i don't want the lines to be blurred too much
16:15:14 <cdent> #action start tracking todos and other planning style issues for wg in launchpad openstack-api-site
16:15:39 <elmiko> sounds good
16:15:48 <cdent> it's cheap enough to have our own
16:16:03 <etoews> cdent: are you saying create our own?
16:16:08 <etoews> (which i'm fine with)
16:16:16 <cdent> easier to navigate it we do
16:16:23 <annegentle> I'm fine with that, openstack-api-wg in lp
16:16:28 <elmiko> my only concern is differentiating between api-site issues and guideline related issues
16:16:37 <annegentle> and there's too many bugs in api-site already :)
16:16:47 <elmiko> ok, maybe best to make a new lp
16:16:50 <etoews> it would require a tag but openstack-api-wg is better
16:16:56 <elmiko> yea, +1
16:17:15 <etoews> is that something we can do right now?
16:17:29 <cdent> yes, I did it for something else yesterday, so I'll do it again
16:17:37 <sdague> anyone that's admin on the group can make official tags
16:17:37 <annegentle> yeah, fairly straightforward
16:17:37 <elmiko> cdent++
16:17:38 <etoews> thanks cdent
16:17:45 <cdent> #action cdent to create openstack-api-wg launchpad
16:18:14 <etoews> moving on...
16:18:17 <etoews> #topic Doc: RST plus parameters YAML files as substitute for Compute API not fitting Swagger/OpenAPI
16:18:26 <etoews> #link https://review.openstack.org/#/c/294078/
16:18:26 * cdent looks at sdague and annegentle
16:18:29 <annegentle> here
16:18:40 <sdague> yeh
16:18:44 <annegentle> sdague: you want to intro?
16:18:58 <sdague> sure the, best place to start is probably the planning etherpad
16:19:04 <sdague> https://etherpad.openstack.org/p/api-site-in-rst
16:19:24 <sdague> I started doing a deep dive into the hard parts of our existing apis and swagger a couple weeks ago
16:19:32 <sdague> and there are some ... intractable problems
16:20:03 <sdague> I think our #1 near term mission should be to get off of WADL, which is causing friction in fixing issues in our user facing API docs
16:20:04 <annegentle> well, problems large enough to need ongoing engineering
16:20:40 <sdague> so in that etherpad is data collection and proposed steps forward to doing an RST first approach to our API
16:20:53 <elmiko> bummer about the swagger problem areas, but looking at the beginning of this etherpad they seem pretty entrenched
16:21:04 <sdague> with plug points (sphinx extensions) for structured data
16:21:26 <sdague> the structured data starting off as a pretty adhoc thing to capture what's currently in the wadl
16:21:35 <annegentle> ideally, we can get that structured data from fairy-slipper migration somehow
16:21:49 <elmiko> imo, getting to the point of projects having rst based api docs seems like a nice short-term goal
16:21:59 <sdague> but those structured data points could be swapped out for things like swagger / raml in the future should we want to go there.
16:22:01 <annegentle> elmiko: yeah, I've come to that as well
16:22:06 <elmiko> especially if those docs are controlled by the projects
16:22:16 <elmiko> sdague: +1
16:22:16 <sdague> once we have a publish pipeline that gets us useful docs to the end user
16:22:35 <annegentle> elmiko: the response I've gotten from reaching out to all the projects hasn't been overwhelming, but the ones that do respond really need to know what they can do
16:22:53 <annegentle> I think this gets us a publishing pipeline, but still requires the work on teams
16:23:08 <sdague> and, trying to keep this scoped narrow enough that it could largely done in this next cycle
16:23:10 <annegentle> I hope it's less engineering time and maintenance. I think it is.
16:23:25 <elmiko> annegentle: seems to me it would be useful to have a template that projects can look at for reference as to how they can create these docs, and where to put them
16:23:49 <sdague> elmiko: yeh, we're going to have a worked example in compute first
16:23:59 <elmiko> if, in the future, we create tooling to help automate the transition between code and docs then so much the better
16:24:03 <sdague> there are POC patches up there for the servers resource being converted over
16:24:16 <sdague> https://review.openstack.org/#/q/status:open+project:openstack/nova+branch:master+topic:wip_api_docs
16:24:20 <annegentle> yes
16:24:22 <elmiko> sdague: cool, have you looked at projects like keystone who keep their descriptive api docs in the specs repo?
16:24:24 <sdague> by putting it in the dev docs for nova
16:24:47 * elmiko looking at nova reviews
16:24:48 <annegentle> nova's not a fan of the specs repo for this elmiko
16:24:48 <sdague> elmiko: I have not really, because this was mostly about getting off WADL
16:25:00 <elmiko> ok, fair
16:25:00 <annegentle> goal 1!
16:25:03 <annegentle> :)
16:25:14 <sdague> my guess is we'd keep this in the core nova repo, much like our api-guide
16:25:23 <elmiko> believe me, i would love to get sahara off the wadl stuff (i think it's out of date anyway)
16:25:38 <sdague> but... there are some chunks of conversion tooling that we need a little bit better first
16:25:48 <elmiko> sdague: ok, i don't have a strong opinion about the where, i just liked keystones approach
16:25:53 <annegentle> elmiko: ok
16:25:58 <elmiko> sdague: yup, +1
16:26:16 <sdague> elmiko: yeh. I think being in specs would also be fine actually.
16:26:20 <etoews> does http://developer.openstack.org/api-ref.html become a landing page linking out to all of the project api docs?
16:26:26 <sdague> it's not going to hugely matter
16:26:30 <annegentle> and also, we took this to the nova api team meeting yesterday, and while they are disappointed a bit to lose swagger, I think they understand the priorities
16:26:35 <dstanek> elmiko: i think we did that partially because of the way specs change the API, made sense to be in the same repo
16:26:36 <sdague> etoews: I think so
16:26:38 <elmiko> i think the tooling will probably take different shapes depending on the wsgi framework used by each project
16:26:42 <annegentle> elmiko: yea it can
16:27:04 <elmiko> dstanek: ack
16:27:06 <sdague> I think the long term should be that each project has their API ref somewhere they can approve
16:27:07 <annegentle> er etoews yea, it can. We still need some good IA/nav on developer.openstack but the idea is to make that site better and not source from wadl
16:27:14 <etoews> that's more or less what it is now anyway with the links being in the left-hand nav
16:27:19 <sdague> they publish to a dedicated subtree on developer.openstack.org
16:27:21 <elmiko> dstanek: i just really appreciate what you folks did with the api docs, +1
16:27:26 <sdague> and there is a top level index
16:27:40 <elmiko> sdague: soo yes to projects controlling their own api docs
16:27:51 <etoews> elmiko: can you provide a #link ?
16:27:52 <annegentle> yep dstanek, next would be to publish that conceptual info to developer.openstack
16:28:03 <annegentle> dstanek: we can talk more after if that's a good outcome to the keystone team
16:28:18 <dstanek> annegentle: sure, that sounds good
16:28:19 <elmiko> #link https://github.com/openstack/keystone-specs/tree/master/api
16:28:44 <elmiko> etoews: i think there is work to be done there in terms of creating a full, in-depth, description of all endpoints. but i like the general approach
16:29:14 <elmiko> but as for a descriptive version of the api docs, i really like the work keystone has done
16:29:49 <annegentle> yeah elmiko +1
16:29:58 <sdague> yeh, I'll look with some of that as well. Though, at the end of the day it's going to be RST, so you can do anything you like
16:29:58 <annegentle> so, you all are okay with a new approach to api reference?
16:30:05 <elmiko> sdague: do you envision their being some sort of config file which projects can propose changes against for the location of their docs?
16:30:10 <annegentle> and the loss of swagger is ok?
16:30:16 * elmiko cries
16:30:21 <elmiko> i'll get over it ;)
16:30:21 <sdague> elmiko: it will be project config somewhere
16:30:23 <annegentle> heh
16:30:33 <elmiko> sdague: +1
16:30:43 <cdent> annegentle: anything is better than paralysis :)
16:30:44 <sdague> I think the important lesson I learned from this research is swagger/raml are API design tools
16:30:53 <sdague> that have the side benefit of a docs toolchain
16:31:01 <annegentle> elmiko: it's sorta the other way round, where each project makes a publish job to developer.openstack
16:31:01 <cdent> sdague++
16:31:05 <elmiko> sdague: i can see that
16:31:09 <annegentle> sdague: yeah
16:31:19 <elmiko> annegentle: ok, that works too =)
16:31:22 <etoews> they also serve well as machine parsable contract between client and server
16:31:38 <sdague> etoews: they could
16:31:42 <elmiko> i mean, i really like the swagger stuff but the whole "actions" and heat template issues are huge
16:31:44 <etoews> (swagger/raml that is)
16:31:49 <sdague> there is very minimal tooling on that at this point though
16:32:19 <etoews> ya. i understand. we need something now. it's okay with me.
16:32:45 <sdague> if our top concern is machine parsable client/server contract, I honestly think we should just propose people make wsdl interfaces :)
16:32:57 <cdent> (etoews there's that whole side issue of "If you need a machine readable contract between client and server then you are doing the web completely wrong...)
16:33:04 <etoews> too cruel man too cruel
16:33:06 <cdent> (but that's not germane at this time)
16:33:07 <annegentle> heh
16:33:23 <sdague> right now I'd like humans to be able to understand our APIs without reading our source code
16:33:27 <sdague> which is mostly not possible
16:33:33 <elmiko> agreed
16:33:37 <cdent> word
16:33:38 <etoews> cdent: hateoas + ??? ftw!
16:33:51 <elmiko> and at least if the projects can control their docs _and_ they are rst it should lower the bar
16:33:57 <annegentle> let's hope so
16:34:00 <sdague> elmiko: right, that was exactly the thinking
16:34:04 * elmiko fingers-crossed
16:34:11 <elmiko> sdague: it's way too sensible ;)
16:34:14 <annegentle> I will draft a "Swagger, where art thou?" email to openstack-dev
16:34:25 <annegentle> outlining the new plan
16:34:27 <etoews> also being able to -1 a code review because it doesn't update api docs is HUGE
16:34:32 <elmiko> etoews: +1
16:34:37 <annegentle> elmiko: 100+
16:34:44 <annegentle> gawd e complete :)
16:34:50 <annegentle> etoews: +100
16:34:51 <elmiko> haha
16:35:01 <etoews> i think we can move on
16:35:04 <annegentle> cool
16:35:06 <annegentle> thanks all
16:35:12 <annegentle> and of course thanks sdague
16:35:20 <elmiko> thanks sdague and annegentle for pushing this forward =)
16:35:24 <etoews> ++
16:35:28 <etoews> #topic Do a cross project session?
16:35:35 <etoews> #link https://etherpad.openstack.org/p/newton-cross-project-sessions
16:35:49 <annegentle> doit
16:35:54 <sdague> I proposed one specific to the API docs discussion
16:35:58 <etoews> we currently have a wg session on monday at 2 pm.
16:36:18 <sdague> as I figured that is going to need socialization and feedback. And hopefully we'll have a good chunk to show there.
16:36:58 <etoews> should we have a more general one for the api wg or does the session on monday suffice?
16:37:03 <elmiko> maybe a q&a session about how the community interacts with the guidelines?
16:37:15 <etoews> that could work
16:37:33 <sdague> although, if it's already in the monday track, that might be duplicative
16:37:40 <elmiko> true
16:37:56 <etoews> monday for working on some stuff (the TODOs?) and tuesday for Q&A?
16:38:00 <elmiko> as for our session, how will we plan it? (i have a few ideas i'd like to present to the wg)
16:38:04 <etoews> ya. there could be overlap.
16:38:37 * etoews stumbles about for etherpad link
16:38:43 <elmiko> i think it would be nice to get a little time at the cp meeting to get the pulse of the community
16:38:47 <sdague> I think if there is something specific we're trying to move forward, that would be better for cross project sessions. Those are really meant to be more typical design summit sessions with goals, discussion, outcomes
16:38:57 <elmiko> ah, ok
16:39:10 <etoews> that's reasonable
16:39:45 <elmiko> i do have some specific ideas/plans around the guidelines and the community, but i would like to propose them to the wg first
16:39:48 <etoews> elmiko: do you have the etherpad link to our wg session?
16:39:58 * elmiko starts digging
16:40:16 <cdent> #link https://etherpad.openstack.org/p/austin-api-wg-session-plans
16:40:26 <etoews> thx
16:40:47 <cdent> I _hate_ etherpad for exactly that reason. It's a place where info goes to be never found again.
16:41:02 <elmiko> totally
16:41:16 * elmiko needs a meta-etherpad to keep track of them all
16:41:22 <cdent> I think they call that a wiki
16:41:25 <cdent> :(
16:41:26 <elmiko> hahaha
16:41:39 <elmiko> i'll add my thoughts to our pad
16:41:39 <etoews> i somehow get the feeling that tuesday would get us more engagement than monday but i'm just basing that on gut feel.
16:42:00 <etoews> sdague: is the cross project day effectively a single track?
16:42:31 <sdague> etoews: no, it has often been a 3 track day
16:42:53 <sdague> we're a bit more flexible in austin though, so it may have more / less tracks at each time block this time
16:43:02 <sdague> as we try to ensure less contention on specific items
16:43:28 <sdague> but for planning purposes, assume 2 other sessions are running against yours for attention
16:43:35 <etoews> k
16:43:55 <sdague> I honestly think monday is probably less attention contention than tuesday
16:44:51 <etoews> okay. let's keep it to monday. and on monday we can identify some of the cross project sessions on tuesday that are relevant to the api wg and try to attend those.
16:45:01 <elmiko> sounds good
16:45:07 <sdague> yeh, that seems like a good strategy
16:45:22 <etoews> movin on...
16:45:22 <cdent> I'm going to mail a photo of my head on a stick to elmiko.
16:45:25 <etoews> #topic Etags and the lost update problem
16:45:34 <elmiko> cdent: sweet!
16:45:41 <elmiko> i will carry it with pride
16:46:10 <elmiko> i'm very curious about this topic, did a bunch of reading after cdent brought it up in -sdks
16:46:12 <cdent> Yeah, so sdague and I kinda stumbled on to the fact that anywhere we suggest people use PUT but don't tell them about Etags we are causing lost update potential
16:46:43 <cdent> #link https://www.w3.org/1999/04/Editing/
16:46:50 <cdent> that's very old but still very true
16:46:51 <etoews> well...PUT as it's supposed to be implemented :P
16:47:05 <sdague> and only swift seems to have any infrastructure to support this at all
16:47:26 <cdent> right the issue is that etags are not a part of the openstack zeitgeist in any fashion
16:47:59 <cdent> So I've already committed to writing an initial informative guideline
16:48:08 <cdent> but there's probably more to think about
16:48:14 <elmiko> nice
16:48:38 <sdague> we're going to need some supporting code for this I think on both the server and client side
16:48:56 <etoews> definitely
16:49:02 <cdent> this probably relates to the above topic about creating issues on launchpad
16:49:29 <cdent> so beyond needing conceptual guidance we need technical guidance
16:49:44 <cdent> it exists out there in the wide world, but we need to bring it local and blessed
16:49:49 <sdague> I don't know how much of it can be done as a pipeline element
16:50:08 <elmiko> is this something that would become an olso lib?
16:50:08 <sdague> it would be nice if the answer included some utility libs, plus a bunch of examples
16:50:37 <cdent> elmiko, sdague: I don't think it is something that can be all that generic, etag generation is complicated
16:50:38 <sdague> sure, or just have the api-wg own it. Not all openstack libs must be oslo.
16:50:44 <sdague> cdent: ok, sure
16:51:06 <elmiko> sdague: ack
16:51:25 <cdent> I mean we migth be able to make it happen, but then it won't be clear and maintainable to the local code
16:51:38 <sdague> sure
16:51:38 <elmiko> i do like the idea of api-wg taking on some code projects, i think it helps the lifeline, but does take us a little away from the initial goal of only creating guidelines
16:51:40 <cdent> I'm not sure what the right path is, I simply wanted to make sure that we start thinking about it.
16:51:53 <sdague> yeh, I think surfacing it as a known issue
16:51:59 <elmiko> +1
16:52:10 <cdent> elmiko: I kinda wondered about that while creating microversion-parse
16:52:16 <elmiko> starting with information seems like a nice step
16:52:20 <elmiko> cdent: yea, exaclty
16:52:41 <etoews> we certainly want to avoid proliferating unmaintained code
16:53:04 <elmiko> +1
16:53:13 <sdague> I feel like it's best to keep code near the expertise. Having api-wg folks maintain some of these libs seems best for that.
16:53:37 <cdent> etoews: it dosn't have to be maintained if begins life correct ;)
16:54:25 <cdent> (correct like my irc typing)
16:54:44 <sdague> cdent: until we get a major python version bump :)
16:54:48 <sdague> as we have discovered
16:54:55 <elmiko> lol
16:55:17 <etoews> we could narrow the scope of microversion-parse to just left padding the header value
16:55:26 <cdent> etoews++
16:55:36 <elmiko> nice...
16:55:40 <dims> LOL
16:55:54 <elmiko> etoews: could we turn it into a microservice too?
16:55:54 <etoews> is there any action here or was this just for discussion?
16:56:09 <cdent> anyway, we've ground that into the ground. I think we all agree that etags matters. The action is
16:56:18 <cdent> #action cdent starts an etag guideline
16:56:26 <cdent> from there we'll move on to sample code
16:56:34 <etoews> ++
16:56:38 <cdent> but I think we need to hash the informative guideline first
16:56:38 <elmiko> sounds good
16:57:02 <etoews> and sample could potentially just live in http://git.openstack.org/cgit/openstack/api-wg/
16:57:15 <etoews> anything else to discuss before we wrap up?
16:57:34 <cdent> seems good stopping point
16:58:09 <etoews> those frozen guidelines, are the ready to merge?
16:58:10 <elmiko> nothing here
16:58:39 <etoews> https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z is not loading for me
16:58:47 <etoews> 503
16:58:49 <cdent> gerrit is taking a little break
16:59:04 <etoews> alrighty
16:59:16 <etoews> thanks all
16:59:30 <etoews> #endmeeting