00:01:30 <elmiko> #startmeeting api-wg
00:01:31 <openstack> Meeting started Thu Apr 30 00:01:30 2015 UTC and is due to finish in 60 minutes.  The chair is elmiko. Information about MeetBot at http://wiki.debian.org/MeetBot.
00:01:32 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
00:01:34 <openstack> The meeting name has been set to 'api_wg'
00:02:18 <elmiko> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
00:02:50 <elmiko> #topic previous meeting action items
00:03:19 <elmiko> #link http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-04-23-16.00.html
00:03:22 <miguelgrinberg> elmiko: looks like you are the only one with an action item
00:03:26 <elmiko> yea
00:03:26 <miguelgrinberg> the only one present
00:03:30 <elmiko> etoews, handled his
00:03:52 <elmiko> i'm still working on the guidelines change, trying to figure out what would be best for inclusion
00:04:02 <sigmavirus24> o/
00:04:05 <sigmavirus24> (sorry I'm late)
00:04:24 <elmiko> i started trying to make the "Change Guidelines" fit the guidelines template, but i'm not totally sure if that's correct
00:04:28 <elmiko> sigmavirus24: no worries =)
00:04:55 <elmiko> i'll put it up for review and we'll see what folks think
00:05:14 <sigmavirus24> cool
00:05:27 <elmiko> #topic guidelines
00:05:45 <elmiko> #link https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
00:05:58 <elmiko> i think everything is pretty much under review at this point,
00:06:04 <elmiko> does anyone want to mention something specific?
00:06:43 <stevelle> nothing here
00:06:45 <miguelgrinberg> When are we lifting the freeze on proposals?
00:06:48 <elmiko> oh, plus we're frozen on miguelgrinberg's proposals
00:07:07 <elmiko> miguelgrinberg: i thought once the kilo release had ended
00:07:27 <sigmavirus24> yeah we didn't discuss when we would unfreeze them
00:07:41 <miguelgrinberg> Kilo releases tomorrow right?
00:07:43 <sigmavirus24> we just discussed the idea that PTLs are kind of super busy now and CPLs are probably busy too
00:07:44 <elmiko> and i think etoews is out until next week
00:07:51 <elmiko> yea
00:08:15 <elmiko> #link https://wiki.openstack.org/wiki/Kilo_Release_Schedule
00:08:30 <elmiko> tomorrow is the release, maybe we should ping etoews through email
00:08:32 <sigmavirus24> Perhaps we'll never unfreeze them. *laughs maniacally*
00:08:34 <miguelgrinberg> Glad to see a spec on filtering is in the works
00:08:35 <elmiko> lol
00:09:21 <elmiko> yea, very cool about filtering. i had questions about the best ways to implement this
00:10:02 <miguelgrinberg> Heat has a couple of specs for Liberty where there is filtering, so it's good that we put something together
00:10:57 <elmiko> sahara is discussing a v2 api and the guidelines have been very helpful in finding problem areas in the current impl
00:11:22 <stevelle> testimonails!
00:11:29 <elmiko> hehe =)
00:11:38 <stevelle> and hopefully fewer typos than me
00:11:46 <sigmavirus24> elmiko: we're going to do a google hangouts podcast series now
00:11:51 <miguelgrinberg> yes, also the nova people reached out for help with tagging
00:11:51 <sigmavirus24> And you'll be the guest
00:12:01 <sigmavirus24> jaypipes: miguelgrinberg and I will grill you on how the API-WG has changed your life =P
00:12:08 <elmiko> awesome... ;)
00:12:44 <elmiko> even though it's not merged yet, the tagging guideline has helped.
00:13:03 <miguelgrinberg> yes, heat already implemented it, and now nova will
00:13:17 <elmiko> nice
00:13:49 <elmiko> anything else for guidelines?
00:14:12 <jaypipes> lol
00:14:27 <elmiko> #topic APIImpact
00:14:32 * sigmavirus24 half-heartedly apologizes for being so punchy tonight
00:14:41 <elmiko> #link https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z
00:14:54 <stevelle> apology half-heartedly accepted?
00:14:57 <elmiko> any reviews we should look at?
00:14:59 <elmiko> lol
00:15:18 <jaypipes> sigmavirus24: did you see my callout to you, miguelgrinberg and etoews in a podcast recently?
00:15:33 <miguelgrinberg> jaypipes: I did! total surprise to hear my name!
00:15:35 <sigmavirus24> jaypipes: my coworker caught it and alerted us
00:15:40 <jaypipes> heh
00:15:46 <elmiko> jaypipes: is that the bootstrapping hour?
00:16:06 <jaypipes> elmiko: no, it was a podcast with Jeff DIckey from redapt and Niki Acosta from Cisco
00:16:16 <elmiko> oh, nice
00:16:19 <jaypipes> elmiko: I need to get with sean about the bootstrapping hour continuing..
00:16:24 <jaypipes> thx for the reminder :)
00:16:37 <elmiko> jaypipes: +1, i've really enjoyed it so far =)
00:16:45 <jaypipes> cool!
00:16:54 <jaypipes> so, guys, I have a bit of API WG news...
00:17:04 <elmiko> #topic News
00:17:04 <jaypipes> sorry for being late to this meeting, first of all
00:17:45 <jaypipes> so, I've been chatting with johnthetubaguy, kenichi, mgilliard and alex_xu about a Nova contributor being a liaison to the API WG
00:17:57 <elmiko> nice
00:18:03 <jaypipes> Looks like alex_xu and mgilliard will be our liaisons.
00:18:23 <jaypipes> I suggested, however, that instead of just showing up to meetings, that they have specific tasks.
00:18:35 <jaypipes> namely, the following. one sec, grabbing copy.
00:19:02 <jaypipes> sorry for the paste, but here it is:
00:19:04 <jaypipes> 1) Assign someone (or some two) people to monitor the active patch queue in
00:19:04 <jaypipes> nova (and nova-specs) and look out for any patch that adds or changes the
00:19:04 <jaypipes> REST API
00:19:04 <jaypipes> 2) For each patch collected in #1, determine if the constructs used in the
00:19:04 <jaypipes> patch (or proposed spec) match the guidance currently laid out in the API
00:19:05 <jaypipes> working group repo's guidance documents.
00:19:07 <jaypipes> 3) If the patch does NOT match the guidance from the API working group, do a
00:19:09 <jaypipes> code review on the patch pointing to the guidance from the API working
00:19:11 <jaypipes> group, and ask the author to align with that guidance. Include in your
00:19:13 <jaypipes> research patches to the API working group that may actually be in review and
00:19:15 <jaypipes> not merged. (An example of this recently occurred with Sergey Nikitin's
00:19:17 <jaypipes> re-proposed instance tagging spec: https://review.openstack.org/#/c/177112/.
00:19:19 <jaypipes> See Ryan Brown's reference to an in-progress API working group guidance on
00:19:21 <jaypipes> tagging)
00:19:23 <jaypipes> 4) If there is NO guidance in the API working group repo for a particular
00:19:25 <jaypipes> proposed API change or addition, create a proposed patch to the API working
00:19:27 <jaypipes> group with guidance that clarifies the missing functionality that is
00:19:29 <jaypipes> introduced in the new Nova patch or spec patch, and bring the proposed
00:19:33 <jaypipes> guidance to the attention of the API working group.
00:20:20 <elmiko> very nice, i especially like #4
00:20:22 <jaypipes> if you guys feel the above is OK, perhaps it's worth codifying it after a test run in Nova and recmomending these steps for other teams to take with their liaisons to the API WG?
00:20:31 <elmiko> +1
00:21:01 <stevelle> seems like a good place to work from
00:21:02 <miguelgrinberg> very good
00:21:02 <elmiko> at the least it provides a solid guide for how other projects can get involved with the wg
00:21:29 <jaypipes> OK, well, we'll give it a shot over in Nova-land and see if it works out well.
00:21:46 <elmiko> thanks for bringing it up
00:22:36 <jaypipes> lemme know if you have any suggestions on improving the steps for liaisons to take. happy to get feedback on it.
00:22:46 <jaypipes> and sorry for dumping paste into IRC...
00:23:11 <elmiko> no worries
00:23:23 <elmiko> #topic open discussion
00:23:37 <elmiko> anything else folks wanna talk about?
00:23:51 <miguelgrinberg> jaypipes: my only suggestion for #4 is that alternatively the liason can alert an active member of the api-wg to write a guideline
00:24:10 <miguelgrinberg> At least in heat-land I find that some people are not interested in proposing something to api-wg
00:24:21 <miguelgrinberg> at least they should get one of us to do it for them
00:24:35 <elmiko> do they have any reason for why that might be?
00:24:47 <miguelgrinberg> nothing special, lack of time I guess?
00:25:01 <elmiko> yea, i can feel that
00:26:27 <miguelgrinberg> I was going to write something on filtering due to heat having a couple of specs in that area, but ryanb beat me to it
00:26:45 <jaypipes> miguelgrinberg: cool, good suggestion, thank you!
00:28:20 <jaypipes> Hey, so are we ready to merge the 3 guidelines that Everett had put on hold?
00:28:38 <miguelgrinberg> we were wondering when is the freeze is going to end
00:28:51 <elmiko> it seemed like they had good acceptance
00:29:15 <jaypipes> Yes, I was wondering when the freeze would end as well.
00:29:24 <elmiko> maybe we should wait till next week to give the PTLs a chance to review after the kilo release?
00:29:32 <jaypipes> I must have missed an email where etoews mentioned that.
00:29:46 <elmiko> it has been a topic of some mystery
00:29:47 <jaypipes> sure, that's cool by me. no rush.
00:30:46 <elmiko> i think the idea was that as we reach the milestone releases we should impose a freeze on guidelines to give the PTLs a chance to breathe without having to worry about reviewing new guidelines
00:30:59 <elmiko> *i think*
00:31:15 <miguelgrinberg> yes, that was the idea
00:31:40 <elmiko> maybe next meeting we'll revisit?
00:32:04 <elmiko> i'm not sure who has +2 aside from etoews
00:32:11 <sigmavirus24> jaypipes
00:32:13 <sigmavirus24> cyeoh did
00:32:15 <sigmavirus24> =(
00:32:17 <elmiko> =(
00:32:54 <annegent_> aww sad time to join :(
00:33:08 <annegent_> sorry I'm late
00:33:13 <elmiko> no prob
00:33:28 <elmiko> annegent_: did you have any topics to discuss?
00:33:54 * annegent_ reads the log to catch up
00:34:40 <annegent_> oo I like the nova liaison ideas jaypipes
00:34:54 <elmiko> cool
00:35:02 <annegent_> yes I had API Reference information: specification for reinvention underway
00:35:13 <sigmavirus24> =D
00:35:17 <annegent_> you following https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda?
00:35:39 <elmiko> sorta, we ran through those topics so i just kinda freestyled
00:35:46 <elmiko> ;)
00:36:09 <annegent_> Hee
00:36:15 <annegent_> ok if I can go I'll go!
00:36:24 <elmiko> please
00:36:42 <annegent_> Okay, so I really want to be rid of WADL
00:36:48 <elmiko> \o/
00:36:50 <annegent_> and want to figure out how to do the work
00:36:51 <jaypipes> ++
00:36:54 <annegent_> so I've written a spec
00:37:12 <annegent_> but it's still even wishy washy about where the work should live -- in the docs team or in the API WG? Discuss.
00:37:24 <annegent_> #link https://review.openstack.org/#/c/177934/
00:37:39 <elmiko> i had question when reading that,
00:37:45 <annegent_> Tom Fifield has a summary post on openstack-docs about automation as well that I'll link to
00:37:58 <elmiko> what happens to things like the keystone api reference they have in their specs repo?
00:38:11 <elmiko> i always found that to be a nice place for the upstream api refs
00:38:12 <annegent_> elmiko: this is for API Reference, that is their "narrative" form documents
00:38:17 <elmiko> ahh, ok
00:38:36 <annegent_> elmiko: yeah there's a difference, but it may also just need to live in specs, that's up for discussion
00:39:05 <annegent_> there's 915 calls just in the first 8 or so services that became OpenStack
00:39:15 <elmiko> would be interesting if each project owned their api-ref in the specs repo, then the "official" api-ref site did some sort of aggregation
00:39:17 <annegent_> that doesn't even count the additional 10? 12? services
00:39:34 <annegent_> #link http://lists.openstack.org/pipermail/openstack-docs/2015-April/006502.html
00:39:41 <annegent_> so that's what I want to hear from you all
00:39:45 <annegent_> automation okay?
00:39:57 <annegent_> specs repos? <project> repos and scrape from their code?
00:40:10 <elmiko> something like that
00:40:22 <elmiko> and i really liked the swagger based ideas, fwiw
00:40:28 <annegent_> is automation awful when you need to provide real user info though?
00:40:43 <annegent_> and do we de-scope to only infrastructure APIs in order to bring the quality level up?
00:40:48 <annegent_> or will each team bring the quality level up?
00:40:52 <elmiko> i think you had a good point about the errors that can creep in from automated docs
00:41:11 <sigmavirus24> So... I'll say this: JSON Schema can be a nightmare. I'm not an expert but I'm not a novice either. If you're going to go with JSON Schema you'll need a validator with good ways of testing things
00:41:21 <annegent_> elmiko: I always think it's a crappier user experience, but Tom does have good points
00:41:37 <annegent_> sigmavirus24: yeah I worry about finding expertise in community sourcing, it's really really hard already
00:41:39 <elmiko> sigmavirus24: are you talking about the validation on a swagger schema?
00:41:59 <sigmavirus24> elmiko: I'm talking about the RST + JSON Schema proposal at the end
00:42:01 <annegent_> Diane Fleming has single handedly done the maintenance and she's unbelieveably fast and it's still not enough
00:42:13 <annegent_> honestly you need JSON Schema for swagger too
00:42:29 <sigmavirus24> So I'm comfortable with JSON Schema, but I'm no expert
00:42:30 <annegent_> if you want to validate you need json schema from what I can see
00:42:32 <elmiko> yea, that's why i asked. and yes Diane is excellent!
00:42:57 <annegent_> she closed something like 80 doc bugs this release and we're still just barely under 170 API doc bugs
00:43:03 <elmiko> wow
00:43:04 <annegent_> so the situation needs fixing
00:43:08 <annegent_> but how?
00:43:22 <sigmavirus24> yeah that's tough
00:44:20 <elmiko> i kinda like the idea of automating the generation of a skeleton json(swagger) output, then each team working to fill in the missing parts
00:44:28 <annegent_> I'm fine with trying automation. 1. Do you think all teams will comply? 2. will it be a worse experience for consumers of the info?
00:45:02 <elmiko> one issue with automation is that projects using pecan will need to add extra markup to their code
00:45:03 <annegent_> (the ops/admin docs are over 550 doc bugs so there's that comparison which is a bit unfair, ha ha)
00:45:13 <annegent_> so, for pecan we already have WADL automation
00:45:16 <annegent_> I don't know if you know that
00:45:29 <elmiko> i did not, although i started down the path of swagger automation for pecan
00:45:30 <annegent_> but yeah there's only ceilometer using pecan?
00:46:09 <elmiko> barbican uses pecan as well
00:46:11 <annegent_> we don't enable flask, correct?
00:46:20 <annegent_> Looking at this list
00:46:21 <annegent_> #link https://github.com/swagger-api/swagger-spec#python
00:47:02 <annegent_> also what do yuo think about descoping to infra-only? non-starter?
00:47:02 <miguelgrinberg> annegent_: that is not just flask, it is a REST extension for flask, but no project uses Flask that I know of
00:47:09 <elmiko> i didn't test the flask based solutions, but it's much easier to generate the swagger from flask
00:47:15 <stevelle> ceilometer wanted to use flask but was directed to pecan as I understand
00:47:17 <annegent_> miguelgrinberg: right, it's not "blessed" centrally
00:47:19 <annegent_> right
00:47:22 <annegent_> stevelle: right
00:47:27 <elmiko> miguelgrinberg: sahara is using flask
00:48:09 <annegent_> Okay so what about only documenting Compute, Block Storage, Object Storage, Identity, Images APIs?
00:48:15 <annegent_> no-go on de-scope?
00:48:41 <miguelgrinberg> elmiko: oh, nice!
00:48:53 <elmiko> i like the idea of every project documenting, but not sure how practical it will be
00:48:59 <annegent_> elmiko: ah I hadn't realized that
00:49:02 <miguelgrinberg> do you think it'll be able to stay on flask or will it go the ceilo way?
00:49:06 <jaypipes> yeah, I feel the same as elmiko.
00:49:15 <jaypipes> I'm torn on this autogeneration stuff, frankly.
00:49:15 <annegent_> miguelgrinberg: it's a free-for-all at this point
00:49:21 <annegent_> jaypipes: go on :)
00:49:22 <elmiko> miguelgrinberg: i think there is pressure for us to move to pecan, but i'm not sure how far we'll get
00:50:05 <jaypipes> annegent_: If it can be shown that we can accurately autogenerate API docs from the code, then I'll play along. I havent' yet seen anything that can do it well though. :)
00:50:19 <annegent_> jaypipes: right, to me, all automation is worser
00:50:22 <annegent_> worser!
00:50:34 <elmiko> i don't think we can fully rely on autogeneration, especially not if we want the level of detail that api-ref currently has
00:50:44 <annegent_> I'm fascinated with autogenerating Swagger 2.0
00:50:50 <stevelle> +1 that
00:50:55 <elmiko> yea, it's got some really cool features
00:50:57 <annegent_> we do a nice job with the Config Ref already, as Tom points out
00:51:06 <stevelle> as a start point it would save a ton of time to get a transition started
00:51:12 <jaypipes> annegent_: well, no, automation in general is betterer. But I'm just wary. The opposite direction -- i.e. code generated from docs -- almost NEVER works, so I'm skeptical about it.
00:51:14 <elmiko> i think it would be nice if we could provide advice on how to autogenerate then markup
00:51:15 <annegent_> two things I haven't investigated to satisfaction with Swagger:
00:51:16 <stevelle> but only if it worked
00:51:30 <annegent_> 1. how to display headers. Object Storage API has like 80 headers
00:51:42 <annegent_> 2. how to indicate array requirements in requests
00:51:58 <jaypipes> annegent_: #2 is certainly possible. #1, I don't know.
00:52:20 <elmiko> yea, i don't remember how #1 work, but i *think* it's in there
00:52:30 <annegent_> #link https://github.com/rackerlabs/wadl2swagger/issues/8
00:52:38 <annegent_> long read, but two teammates couldn't figure it out jaypipes
00:52:57 <annegent_> this is all useful. Would you like to have a session on this at the Summit? I think I can find time
00:53:12 <annegent_> I know docs has a slot for API docs specifically to discuss this spec.
00:53:23 <annegent_> now, do we make it a docs spec, or an API WG guideline? Discuss.
00:53:42 <annegent_> as in, "review all code patches to comply with this API WG doc guideline"
00:53:45 <annegent_> would that work?
00:53:56 <elmiko> i see several references to headers in https://github.com/swagger-api/swagger-spec
00:53:59 <jaypipes> annegent_: a docs spec.
00:54:28 <elmiko> annegent_: i'd make time for a discussion at summit
00:54:52 <annegent_> jaypipes: ok
00:54:58 <elmiko> agreed with jaypipes, especially if it continues to be a doc site production for the html side of the api-ref
00:55:17 <annegent_> #link http://rackerlabs.github.io/wadl2swagger/openstack.html
00:55:25 <jaypipes> annegent_: verified in the 2.0 swagger spec, it has full support for HTTP headers in both request and response.
00:55:28 <annegent_> but for whatever reason we don't have an Object Storage API swagger there
00:55:44 <annegent_> so I need to figure out "whatever reason"
00:56:00 <annegent_> Okay, I think that was all my questions.
00:56:11 <elmiko> wadl2swagger is a nice start, but imo we should ultimately help projects to autogen the base swagger
00:56:21 <annegent_> #action please comment on the docs spec at https://review.openstack.org/#/c/177934/
00:56:37 <annegent_> #action please reply on the openstack-docs mailing list thread here: http://lists.openstack.org/pipermail/openstack-docs/2015-April/006502.html about automation
00:56:48 <annegent_> elmiko: agreed
00:56:56 <elmiko> thanks for bringing this up annegent_
00:57:18 <annegent_> elmiko: thanks for letting me crash in late!
00:57:20 <annegent_> :)
00:57:29 <elmiko> always =)
00:57:54 <elmiko> ok, any other last minute notes?
00:58:08 * sigmavirus24 has none
00:58:17 <miguelgrinberg> nope
00:58:35 <elmiko> thanks for coming out everyone!
00:58:41 <elmiko> #endmeeting