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