12:00:35 <alex_xu> #startmeeting nova api 12:00:36 <openstack> Meeting started Fri May 8 12:00:35 2015 UTC and is due to finish in 60 minutes. The chair is alex_xu. Information about MeetBot at http://wiki.debian.org/MeetBot. 12:00:37 <eliqiao1> cool 12:00:38 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 12:00:40 <openstack> The meeting name has been set to 'nova_api' 12:00:51 <alex_xu> welcome to nova api meeting! 12:01:09 <eliqiao1> hi, host , alex_xu: 12:01:17 <alex_xu> eliqiao1: hah 12:01:29 <alex_xu> gilliard_afk: is on vacation also 12:01:55 <sdague> oh, hey folks 12:01:58 <eliqiao1> so let's wait for a while... 12:02:04 <alex_xu> sdague: hi 12:02:15 <sdague> are we expecting jaypipes ? 12:02:33 <alex_xu> sdague: yes, there is one item asked by jaypipes 12:03:21 <alex_xu> ok...let run the meeting 12:03:29 <alex_xu> #topic Vancouver summit 12:03:40 <alex_xu> #link https://etherpad.openstack.org/p/YVR-nova-api-2.1-in-liberty 12:03:45 <alex_xu> #link https://etherpad.openstack.org/p/YVR-nova-api-2.0-3rd-party 12:03:53 <alex_xu> We have new etherpad for summit now. Thanks for johnthetubaguy update it! 12:04:14 <alex_xu> It is worth everybody read it before the summit 12:04:37 <alex_xu> and review 12:05:08 <annegentle> alex_xu: ideally you'll add a line about 2.1 docs, Diane Fleming has done a lot of work, and there's also a spec I've added to the agenda for today. 12:05:30 <annegentle> I don't want to add to the agenda for the Summit session since we have docs sessions elsewhere 12:05:48 <sdague> annegentle: any idea which session happens first? 12:06:47 <alex_xu> annegentle: you want to add a line in the first api session? 12:07:37 <alex_xu> annegentle: are you still there? 12:07:58 <alex_xu> let's move, I guess annegentle will back later 12:08:11 <alex_xu> #topic OverQuota return 400 vs 403 12:08:18 <alex_xu> This is good point from sdague 12:08:23 <alex_xu> #link http://lists.openstack.org/pipermail/openstack-dev/2015-May/063396.html 12:08:41 <alex_xu> jaypipes: ^ are you here? 12:09:05 <alex_xu> sdague: One point from api-wg meeting is make sense to me: After we have sub-error-code, the status code can be used for 'top level filter' in the client code. 12:09:06 <annegentle> sdague: hmm 12:09:08 <annegentle> looking 12:09:23 <annegentle> sorry for the pause; getting kids to school 12:09:42 <sdague> alex_xu: yeh, honestly the errors json spec is what we need here, evertte pointed it out 12:10:13 <sdague> realistically I think the http.rst is extremely sparse in the api-wg repo, and misses a lot of why 12:10:28 <sdague> if I get a chance I'm going to push some things up to it for review before summit 12:10:50 <sdague> to try to explain existing reasons 12:11:12 <sdague> I also ended up -1ing some patches that were adding/consolidating the 501 error codes, because those are all wrong 12:11:33 <sdague> but I'm not sure we've yet decided the right thing there 12:11:52 <alex_xu> sdague: why 501 is wrong? 12:12:06 <sdague> because METHOD means something *extremely* specific in HTTP 12:12:28 <sdague> METHOD is one of GET / POST / PUT / HEAD / DELETE / OPTIONS 12:12:34 <eliqiao1> sdague: curretnly , lots of 501 in v2.1 apis 12:12:35 <alex_xu> sdague: I see now, you mean GET/POST...not implement 12:12:37 <sdague> it does not mean "cells feature isn't enabled" 12:12:44 <sdague> alex_xu: correct 12:13:14 <alex_xu> sdague: what your expect for the our code not implement some function? 12:13:17 <eliqiao1> do we need to clean up them ? 12:13:33 <sdague> this is the unfortunate thing that happens when people only read the error codes section, and not the whole spec 12:13:43 <sdague> which is the same issue with the quota 403 thing 12:14:01 <sdague> eliqiao1: well, I think we need to figure out a consistent fix to get to 12:14:08 <sdague> which is not yet decided 12:14:27 <alex_xu> sdague: so hope we can get consistent on the summit 12:14:37 <alex_xu> sdague: is there api-wg session for it? 12:14:42 <sdague> alex_xu: I don't know 12:14:49 <eliqiao1> sdague: how about add each api method possible error code to api-ref ? 12:15:12 <alex_xu> sdague: emm....so how to push we get agreement on it? 12:15:15 <annegentle> there is an api-wg session let me dig up the link 12:15:56 <sdague> eliqiao1: right, so I was going to push up a set of reviews to the api-wg spec with some ideas. I think, honestly, we're just getting to uncover these issues now 12:16:33 <sdague> because when I originally argued against 501 2 years ago, there were very few people that had read the whole spec, and I got over ruled :) 12:16:53 <eliqiao1> #link http://developer.openstack.org/api-ref-compute-v2.1.html this doc is completly wrong 12:17:01 <sdague> but it seems like we've got more people familiar now, so hopefully we can get there 12:17:06 <sdague> eliqiao1: yes, it is 12:17:08 <eliqiao1> and missing some api methods now.. 12:17:19 <sdague> eliqiao1: it's a starting point 12:17:27 <annegentle> #link api wg https://libertydesignsummit.sched.org/event/e14d84514003140fe30e984027299a44#.VUypQtNViko 12:17:37 <alex_xu> annegentle: thanks 12:17:45 <annegentle> eliqiao1: I want to talk about my spec for updating that set of pages 12:18:05 <eliqiao1> annegentle: that would be cool.. 12:18:43 <alex_xu> ok, so hope we get agreement on error code, let stop any patch for correct error code first I think 12:18:51 <alex_xu> let's move on 12:19:02 <alex_xu> #topic Rework API Reference Information blueprint 12:19:07 <alex_xu> annegentle: your turn 12:19:11 <annegentle> dat's the one! 12:19:34 <annegentle> So, as we all recognize, the pages at http://developer.openstack.org/api-ref-compute-v2.1.html are showing their age and lack of maintenance 12:19:50 <alex_xu> annegentle: yes, agree 12:19:53 <annegentle> #link https://review.openstack.org/#/c/177934/ 12:20:15 <annegentle> I'm writing that spec and bringing it to the Design Summit in hopes of refreshing both the out put and the way its updated 12:20:39 <annegentle> Last release, we moved the "compute-api" repo to openstack-attic and brought the version 2 API docs to nova/doc/source 12:21:08 <annegentle> This release, I want to 1) recombine the narrative with the reference and 2) redo how the reference is created 12:21:24 <annegentle> For the 2), we are investigating autogenerating Swagger 2.0 from the nova source code 12:21:34 <annegentle> I may start with glance first, but also wanted to ask this group your thoughts. 12:22:10 <annegentle> because the first scope priority will be compute-related APIs - identity, compute, images, block storage, networking 12:22:30 * alex_xu actucally no idea about doc...he need reading more background 12:22:45 <annegentle> alex_xu: great! sure, it's a lot to digest 12:23:07 <alex_xu> annegentle: is there any plan to support microversion in your spec 12:23:20 <annegentle> #link https://libertydesignsummit.sched.org/event/29e7d4effc10832b4d6aa50339e0c973#.VUyqs9NViko 12:23:51 <annegentle> alex_xu: I'm discussing that but in a slightly different way... because our users need to know "what version of OpenStack has this API call?" 12:24:19 <annegentle> alex_xu: so microversions help with that use case, but other projects don't have them, so I have to figure out how to use metadata for each call to indicate to consumers what clouds have the call 12:24:47 <alex_xu> annegentle: ok 12:24:53 <annegentle> That link above is for the session where we'll talk about scraping code to autogenerate the API reference -- and I'm very very cautious about the approach because I don't want to make the experience bad for end users. 12:25:13 <annegentle> but we just aren't keeping up, and need the reviews to be by the people like sdague who know the history and context :) 12:25:36 <eliqiao1> annegentle: end users are facing doc directly, so, we may need their voice . 12:25:52 <sdague> annegentle: oh dear, waiting on me seems like a terrible idea :) 12:25:53 <annegentle> but for example, if the docs are built from code that gets in with an incorrect 500 error, we don't have defensible docs, you know? 12:26:12 <annegentle> sdague: not waiting :) but we'll need reviewers from the code bases basically 12:26:28 <annegentle> sdague: is it a terrible idea to scrape the code? risky? bad for end users? 12:26:38 <annegentle> sdague: or sorta the place we're at with the scale of projects? 12:26:40 <sdague> though, seriously, poke me in IRC on reviews you need my eyes on, my inbound queue is big enough so I won't end up seeing some of this otherwise 12:26:52 <annegentle> sdague: got it, (same for me) 12:27:04 <annegentle> Does anyone have concerns with migrating away from WADL? 12:27:09 <annegentle> Concerns with Swagger 2.0? 12:27:23 <annegentle> versioning concerns? 12:27:34 <sdague> annegentle: I'm super happy to get away from WADL, as it always hurt my head 12:28:03 <annegentle> sdague: for real. Diane's pretty much our only expert (well and me) 12:28:09 * alex_xu check WADL today...really hurt head... 12:28:19 <annegentle> Swagger seems like it's still tough to find experts in 12:28:28 <annegentle> but at least it's modern, has a community around it. 12:28:59 <annegentle> Okay, one more bit of info 12:29:05 <annegentle> then I'm done :) 12:29:20 <annegentle> The Fuel team has a patch up on stackforge that scrapes the python code to generate Swagger. 12:30:05 <alex_xu> annegentle: thanks for all the info! 12:30:14 <annegentle> #link https://review.openstack.org/#/c/179051/ 12:30:24 <annegentle> thanks for letting me add to your agenda! 12:30:37 <annegentle> thank goodness it came up AFTER the kids went to school ha ha :) 12:30:48 <sdague> annegentle: it would be neat if that was in a more generic tool that could be used on multiple repos 12:31:00 * eliqiao1 take a quick on #link http://editor.swagger.io/#/ , it 's really cool things. 12:31:11 <annegentle> sdague: yeah, seems like that would gain us efficiencies for better app dev docs 12:31:35 <annegentle> eliqiao1: yeah it's so nice it has a non-proprietary editor even if we don't think we'll be editing much 12:32:20 <johnthetubaguy> so, having just decided on json schema and json home, where does swagger fit in? 12:32:44 <annegentle> johnthetubaguy: ah didn't know that, that's why I'm here! 12:32:50 <johnthetubaguy> honestly, looks like a cool ecosystem that will help us 12:33:08 <sdague> johnthetubaguy: so... in nova we use json schema for data enforcement 12:33:12 <johnthetubaguy> annegentle: "decided" should probably have said "leaning twoards" 12:33:13 <annegentle> johnthetubaguy: json schema works with swagger 12:33:20 <sdague> swagger is kind of one level up from that 12:33:31 <sdague> and describes the whole API 12:33:36 <annegentle> johnthetubaguy: json home in my understanding is just a discovery 12:33:45 <johnthetubaguy> sdague: yeah, we were talking about json home and schema for responses, seems like swagger does some of that 12:33:57 <sdague> johnthetubaguy: honestly, I think they all kind of play together 12:34:13 <johnthetubaguy> sdague: yeah, i was going to say, no reason not to have all of these, in some ways 12:34:22 <annegentle> johnthetubaguy: one other project has json home already (barbican?) 12:34:46 <johnthetubaguy> annegentle: oh, I heard keystone too I guess? but never went to check 12:34:55 <johnthetubaguy> anyways, sorry, just food for thought 12:35:04 <alex_xu> yes, json-home is ready in keystone 12:35:05 <annegentle> and glance has json schema on a GET call 12:35:05 <johnthetubaguy> the correct answer feels like its a combination of these things 12:35:08 <sdague> annegentle: perhaps, that would be a really good API WG / Doc team output 12:35:12 <annegentle> johnthetubaguy: oh it's exactly what I need to know 12:35:17 <sdague> a crisp view of how all these fit together 12:35:23 <annegentle> sdague: ah, yes 12:35:31 <sdague> and a set of recommendations in using them 12:35:32 <annegentle> sdague: I plan to shape that spec into that doc 12:35:38 <sdague> annegentle: great 12:35:45 <johnthetubaguy> sdague: yeah, if we combine these, lets do it in the same way cross projects 12:35:58 <annegentle> sdague: and then on the API WG side we'll have a guideline for "this is adequate doc that we'll be reviewing with" 12:36:02 <annegentle> johnthetubaguy: right 12:36:06 <sdague> yep 12:36:28 <johnthetubaguy> quite excited to see us getting someone on this stuff 12:36:31 <annegentle> ok then all that's left is a pile of work! I hope you'll help me recruiting interested parties. The API WG is happy. 12:36:45 <annegentle> johnthetubaguy: I am too! So nice to focus! 12:37:11 <johnthetubaguy> sdague: looking at swagger, we might need a separate one for each micro version? that sounds a bit evil… 12:38:00 <annegentle> johnthetubaguy: I really wonder that myself, and need to investigate. But if we're scraping for them anyway it's a bit like what we've had to do with WADL without human intervention. 12:38:16 <annegentle> by "scraping for them" I mean creating swagger docs by scraping 12:38:37 <annegentle> another thing we could do is use a wadl2swagger tool to migrate 12:38:45 <annegentle> but that still requires human maintenance 12:39:01 <annegentle> I guess we could still autogenerate only on added calls? 12:39:02 <sdague> so, honestly, the wadl in nova is gorpy enough, that we should just come up with a starting from scratch approach 12:39:16 <annegentle> sdague: yeah good point, garbage in garbage out 12:39:41 <sdague> honestly, right now, getting those docs together is probably the most important part of liberty API work, fixing inconsistencies are probably either late cycle, or next cycle 12:39:49 <sdague> I'd say get the docs together for this cycle 12:39:49 <annegentle> sdague: ++ 12:40:00 <alex_xu> sdague: +1 12:40:03 <annegentle> oh one question here 12:40:08 <johnthetubaguy> sdague: I would sign up to that 12:40:11 <eliqiao1> +1 for doc 12:40:16 <annegentle> does nova gate test the request/responses still? 12:40:23 <annegentle> it did for v2, does it for v2.1? 12:40:34 <sdague> annegentle: yes, through the samples mechanism 12:40:35 <annegentle> I think other projects could learn alot from that and we should document it 12:40:40 <sdague> same as before 12:40:45 <annegentle> sdague: so I need to study that and get that into this spec as well 12:41:34 <johnthetubaguy> we might want to tweak all that if we get the docs right 12:41:46 <sdague> annegentle: sure, though it is a bit gorpy as well cdent has some interesting work with a better framework of doing that. It would be good to loop him in as well. 12:41:50 <sdague> johnthetubaguy: yeh 12:42:19 <annegentle> sdague: oh yeah, gabbi right? 12:42:23 <sdague> yes 12:43:09 <alex_xu> looks like we can move on 12:43:18 <alex_xu> annegentle: any more you want talk about? 12:43:24 <annegentle> nope that's it 12:43:29 <johnthetubaguy> does this change the plan for the summit, I guess we need a concrete proposal to review there? 12:43:33 <alex_xu> annegentle: thanks for the info 12:45:21 <alex_xu> johnthetubaguy: I remember there is session provided by annegentle you probably can get from the meeting log 12:45:52 <alex_xu> #topic Open Discussion 12:45:58 <alex_xu> any open? 12:46:45 <eliqiao1> I'd like to request some api sepc review from cores :) , related error code changes ... and some .. 12:46:59 <eliqiao1> backwards-incompatile changes. 12:47:03 <alex_xu> eliqiao1: sure go ahead 12:48:19 <alex_xu> eliqiao1: emm... any link? 12:48:33 <eliqiao1> I put them here #link https://etherpad.openstack.org/p/eli_v2_1_spec hope some one help to review. 12:49:06 <alex_xu> eliqiao1: ok, thanks 12:49:32 <johnthetubaguy> eliqiao1: you say missing properties? they are stuff thats never been in the API right? 12:49:50 <eliqiao1> johnthetubaguy: yes 12:49:52 <alex_xu> and adverties policy patch also, the patch related to service, compute_node and quota are in good shape appreciate any review https://review.openstack.org/#/q/status:open+project:openstack/nova+branch:master+topic:bp/nova-api-policy-final-part,n,z 12:50:06 <sdague> eliqiao1: so... honestly, is there a real urgency here? I feel like I'd be much more comfortable if we actually focussed on documentation and internal cleanup this cycle. 12:50:20 <johnthetubaguy> sdague: you talks the words out of my fingers 12:50:24 <johnthetubaguy> took^ 12:50:35 <eliqiao1> sdague: agreed, sure doc's first. 12:50:46 <johnthetubaguy> eliqiao1: and policy clean up, etc 12:51:08 <eliqiao1> johnthetubaguy: sure :) 12:51:16 <alex_xu> a lot of clean up 12:51:27 <johnthetubaguy> alex_xu: the question was about the Nova session, not the doc track one 12:51:27 <sdague> johnthetubaguy: right, policy cleanup and removing v3 from the filesystem (which confuses people when they go digging around to find an answer) 12:51:38 <johnthetubaguy> sdague: yeah 12:52:08 <johnthetubaguy> so we have a lot of agreement here, I guess I am trying to be sure we know what points need debate at the summit session 12:52:17 <eliqiao1> lot so v3 ,both in source code and directory name. so that's the best naming of v3(v2.1)? 12:52:26 <johnthetubaguy> (there is no point just tell people plans really) 12:52:36 <sdague> johnthetubaguy: so, I think the sessions are still good for building a more structured plan 12:52:55 <sdague> and doing so in a public forum that can hopefully pull in some additional volunteers 12:53:05 <johnthetubaguy> true 12:53:16 <sdague> because there is a lot of work in all that cleanup, and a lot of work that people new to nova could even help with 12:53:33 <johnthetubaguy> yeah, very true 12:53:47 <alex_xu> yea, and those cleanup are easy for new people 12:53:48 <sdague> I think the goal of those sessions should be a quite detailed set of things that want to be accomplished, with milestones 12:54:01 <sdague> and volunteers on both the writing of the code and reviewing of it 12:54:04 <eliqiao1> for clean up in api works, do we need some specs to cover it? 12:54:07 <sdague> so that we can keep that train moving 12:54:39 <johnthetubaguy> sdague: right, I am really just wanting to be sure we have a clear list before we go into the session I guess 12:54:40 <sdague> eliqiao1: I think from that session we can figure out if anything needs a detailed spec 12:54:58 <sdague> johnthetubaguy: so I think the high level todos are in the etherpads for those sessions already 12:55:10 <sdague> <alex_xu> #link https://etherpad.openstack.org/p/YVR-nova-api-2.1-in-liberty 12:55:11 <sdague> <alex_xu> #link https://etherpad.openstack.org/p/YVR-nova-api-2.0-3rd-party 12:55:24 <eliqiao1> sdague: okay, cool 12:55:58 <johnthetubaguy> sdague: I typed those out this morning, just wondering if they are correct still 12:56:25 <sdague> I think so, though I will defer to alex_xu on that question 12:56:40 <sdague> alex_xu: is there anything else you think didn't get captured in those that came up here? 12:56:41 <alex_xu> I will review the etherpad 12:56:48 <johnthetubaguy> anyways, we have lots of eyes on them, so thats awesome 12:56:50 <sdague> alex_xu: great 12:56:54 <johnthetubaguy> alex_xu: thank you :) 12:57:14 <alex_xu> sdague: should we put more detail about what allowed for microversion bump, which can help on dicussion? 12:57:19 <alex_xu> johnthetubaguy: np 12:57:49 <alex_xu> let me check the etherpad, if I have any question will reach you guys 12:58:07 <eliqiao1> sdague: there are still one change about policy.d which is reverted by sean at the end of Kilo. 12:58:17 <alex_xu> we close to time, and we don't have meeting next week? 12:58:43 <eliqiao1> alex_xu: forget to adding on #link https://etherpad.openstack.org/p/YVR-nova-api-2.1-in-liberty ? 12:58:50 <alex_xu> eliqiao1: yes, the performance about policy.d 12:59:09 <sdague> alex_xu: yeh, we should probably discuss guidelines for API version changes in microversions 12:59:15 <sdague> that should end up in tehre 12:59:25 <alex_xu> eliqiao1: there is performance item in the etherpad, is it for policy.d johnthetubaguy ? 13:00:28 <alex_xu> ok, it's time to finish the meeting, thanks for all join the meeting I host at first time! 13:00:29 <johnthetubaguy> alex_xu: I think I mentioned it, but its worth checking 13:00:38 <alex_xu> johnthetubaguy: ok, will check it 13:00:40 <alex_xu> #endmeeting