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