12:00:30 <alex_xu> #startmeeting nova api
12:00:31 <openstack> Meeting started Tue Sep 29 12:00:30 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:32 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
12:00:34 <openstack> The meeting name has been set to 'nova_api'
12:00:39 <alex_xu> who is here today?
12:00:52 <edleafe> o/
12:00:59 <gmann_> hi
12:01:26 <sdague> o/
12:01:26 <alex_xu> hello
12:01:47 <alex_xu> ok, let's run the meeting
12:01:51 <alex_xu> #topic actions from last meeting
12:01:56 <alex_xu> alex_xu eliqiao check max length of hostname on linux and windows again
12:02:09 <alex_xu> we did that and patch merged
12:02:13 <alex_xu> #link https://review.openstack.org/#/c/224438/
12:02:22 <alex_xu> alex_xu catch gmann about backport patch or work on it if have enough time
12:02:29 <alex_xu> Thanks to gmann work out the backport patch
12:02:35 <alex_xu> #link https://review.openstack.org/227135
12:02:45 <alex_xu> i also work out another one
12:02:51 <alex_xu> #link https://review.openstack.org/228774
12:03:23 <alex_xu> hope everyone can review them, or I will catch up some stable branch core
12:03:39 <johnthetubaguy> so all the stable patches will get a -2, until RC2 opens next tuesday
12:03:41 <sdague> I just +2ed from stable perspective
12:03:46 <johnthetubaguy> but I like us getting those lined up ASAP
12:03:49 <sdague> johnthetubaguy: this is kilo
12:03:54 <johnthetubaguy> oh, my bad
12:03:55 <alex_xu> johnthetubaguy: those are kilo
12:04:04 <johnthetubaguy> is kilo out of its freeze?
12:04:05 <gmann_> yea
12:04:45 <johnthetubaguy> I should really pay more attention, and stop using my not on stable-core as an excuse
12:04:45 <alex_xu> johnthetubaguy: there is freeze for kilo?
12:05:14 <johnthetubaguy> there was a stable freeze at some point, while they cut a new release, or some such, its probably happened already
12:05:44 <alex_xu> ok, I can catch some stable-core to review them
12:06:05 <alex_xu> #action alex_xu catch up stable-core review the api bug kilo back-port
12:06:11 <alex_xu> johnthetubaguy contact the doc team to see what we can help on missing stuff in the doc
12:06:19 <johnthetubaguy> yeah, so I failed to do that
12:06:26 <johnthetubaguy> but, they do have the last patch up for that bug
12:06:45 <johnthetubaguy> so I plan on taking a look at that, and see what more needs doing
12:06:49 <johnthetubaguy> #link https://review.openstack.org/#/c/227672/
12:07:15 <alex_xu> johnthetubaguy: ok, thanks
12:07:21 <johnthetubaguy> part of me wants to remove v2, v2 extensions and v2.1 and just have a single doc for "compute API" that describes the details
12:07:32 <johnthetubaguy> but lets talk about that later in the agenda
12:07:36 <gmann_> johnthetubaguy: so they are updating wadl manually?
12:07:39 <edleafe> johnthetubaguy: me too
12:07:45 <johnthetubaguy> gmann_: yes, basically
12:08:18 <alex_xu> johnthetubaguy: do you want another action?
12:08:57 <alex_xu> #topic  API Concept Doc
12:09:10 * alex_xu jump the topic directly
12:09:18 <alex_xu> #link https://review.openstack.org/226253
12:09:19 <johnthetubaguy> alex_xu: thats fine, yeah, lets talk about it here
12:09:58 <johnthetubaguy> thanks for the update there
12:10:02 <alex_xu> after we merged that patch, we can add more doc on it
12:10:06 <alex_xu> johnthetubaguy: np
12:10:48 <johnthetubaguy> yeah, feel free to hand patches off that change, I guess
12:11:09 <johnthetubaguy> we should talk about those API reference docs
12:11:34 <johnthetubaguy> what do people think about just going to a single doc about the compute API, with a quick description about the extensions
12:11:36 <johnthetubaguy> and versions
12:12:14 <alex_xu> looks like, anyway v2.1 and v2 is equal except few things
12:12:15 <johnthetubaguy> I was thinking each bit could get required/related extensions: X, Y, Z and min_version: 2.6 or something like that?
12:12:40 <johnthetubaguy> the problem is v2 is split into two, which kinda gives the wrong message, I feel
12:12:58 <edleafe> I think any docs moving forward should be about the current API. Then add a comment somewhere about legacy stuff
12:13:08 <sdague> honestly, I like the idea of a unified document
12:13:12 <alex_xu> johnthetubaguy: what means v2 split into two?
12:13:14 <johnthetubaguy> well, I think we need the version history as it evolves
12:13:24 <edleafe> Those docs should be separate so they can be removed when v2 goes away
12:13:35 <johnthetubaguy> alex_xu: so I was super unclear, I really mean v2 vs v2 extensions, but I also mean those two and v2.1
12:13:36 <gmann_> johnthetubaguy: microversion as separate or embedded in same doc
12:13:47 <sdague> edleafe: right, except v2.1 and v2 are basically the same thing
12:13:53 <johnthetubaguy> edleafe: v2 will never go away through really, thats the bit I like
12:14:00 <sdague> it was kind of the point :)
12:14:05 <johnthetubaguy> sdague: yeah, thats a better way of putting it
12:14:35 <edleafe> well, true, except for extensions
12:14:39 <sdague> sure
12:14:47 <sdague> but those bits can be called out
12:14:48 <johnthetubaguy> gmann_: I prefer embedded my self, but I think honestly the tooling will end up deciding that, I am really focusing about getting v2.1 base version accurate first
12:15:02 <johnthetubaguy> yeah
12:15:06 <gmann_> ok
12:15:14 <johnthetubaguy> I was thinking we treat extensions and versions in a similar way
12:15:37 <johnthetubaguy> for this to be there in v2, you need to see extension XYZ, for v2.1 this needs version 2.6, or whatever it is
12:15:50 <gmann_> but extension we can just remove as those are anyways deprecated..
12:15:51 <johnthetubaguy> for v1.1 its the same as v2, etc
12:16:04 <johnthetubaguy> gmann_: well its still in the API, technically, it just becomes less important
12:16:33 <edleafe> I think we should always refer to v2 in the docs as 'legacy v2'
12:16:46 <johnthetubaguy> edleafe: so there are two things here
12:17:04 <johnthetubaguy> endpoint /v2.0 and the legacy v2 code base
12:17:23 <johnthetubaguy> the docs for the API should not ever mention the code
12:17:42 <johnthetubaguy> well, I don't really mean that, but hopefully that makes sense in some world
12:18:06 <edleafe> johnthetubaguy: I was referring to the v2 API design, with extensions, etc.
12:18:12 <edleafe> not the code base behind it
12:18:46 <edleafe> but in the same way we marked the code as legacy for devs, we refer to the API as legacy for consumers
12:18:51 <johnthetubaguy> OK, so I call that v2.0 because thats not v2.1 so its spearate from the legacy v2 implementation, but maybe thats dumb
12:19:00 <johnthetubaguy> well its not really legacy
12:19:24 <johnthetubaguy> its just an endpoint that is unlikely to ever die and will get no new features, hmm, so maybe it is
12:19:45 <johnthetubaguy> anyways, I would rather they not have names as such
12:19:47 <edleafe> to-may-to, to-mah-to :)
12:20:02 <sdague> so, I think this is consistent if we have 1 document, then with resources that were in the extension set in v2 we just comment it with "this used to be an extension in the API, not all cloud providers may have it enabled."
12:20:04 <johnthetubaguy> we can reference the URLs more, so I hope thats clerer in the docs
12:20:04 <sdague> or something
12:20:12 <johnthetubaguy> sdague: +1
12:20:22 <johnthetubaguy> sdague: thats what I am attempting to say, badly
12:20:30 <sdague> but, honestly, we should start with a holistic view and comment where it deviates
12:20:46 <johnthetubaguy> yeah, I like us focusing on the base v2.1 version to start with
12:20:47 <sdague> and, also probably comment where things are defcore required elements
12:20:50 <gmann_> +1
12:21:21 <johnthetubaguy> sdague: so the service catalog and it pointing to a version, do we have a transition plan sorted yet?
12:21:53 <alex_xu> we are talking about the current wadl doc, or the future swagger generated doc?
12:21:53 <gmann_> extension or core api, in some column like option/positional req param
12:21:56 <sdague> no, I'm chatting with stevemar in a couple of hours about some of the service catalog stuff going forward
12:22:16 <sdague> and have the summit as my deadline for proposals on all of this
12:22:25 <johnthetubaguy> I like the idea of making a new endpoint, called os-compute (don't think any folks use that today) point at / so users know about the versions from the version list
12:22:28 <sdague> I've got some ideas about how it would work
12:22:41 <johnthetubaguy> sdague: cool, lets leave that alone for now then
12:22:52 <sdague> I feel like os- is overkill given that it's the openstack service catalog
12:23:03 <johnthetubaguy> alex_xu: gmann_: I am really thinking about the current one, with a nod to swagger
12:23:05 <sdague> but, I do get that we have a problem with existing values there
12:23:37 <johnthetubaguy> sdague: understood, I was just thinking about how to describe it in the API docs really
12:24:06 <johnthetubaguy> so for swagger
12:24:07 <sdague> yeh, that's fair, I think it's just going to be a bit undefined for a bit
12:24:17 <johnthetubaguy> sdague: yeah, true
12:24:21 <alex_xu> johnthetubaguy: I just was thing, if that doc generated from swagger, how to describe the little different between v2 and v2.1
12:24:29 <johnthetubaguy> swagger I think is likely to generate a new doc tree for each version
12:24:38 <sdague> there must be some way to provide comments right?
12:24:40 <johnthetubaguy> so we can create a v2.0 and v2.1 v2.2, etc
12:24:52 <alex_xu> sdague: yea, right
12:25:01 <johnthetubaguy> sdague: yeah, I think we just add the extension stuff as a comment in the v2.0 one
12:25:15 <alex_xu> ok, that may not a problem
12:25:32 <johnthetubaguy> it all seems OK-ish
12:25:40 <johnthetubaguy> v1.1 can just redirect to v2.0, etc
12:25:55 <sdague> yeh, do we have some test bits out there to play with the swagger parts
12:25:58 <alex_xu> ok, so basically we are ok with unifed doc for v1.1, v2 and v2.1, right?
12:26:12 <johnthetubaguy> for the current version of the doc, yes
12:26:36 <alex_xu> cool
12:26:45 <johnthetubaguy> for swagger, I think they end up being the same page with multiple links, then we add changes in future ones for v2.2, etc
12:27:01 <alex_xu> #info we hope to have unifed api ref doc for v1.1, v2 and v2.1
12:27:02 <edleafe> Is v1.1 still used anywhere?
12:27:13 <johnthetubaguy> edleafe: its in our default install
12:27:25 <johnthetubaguy> it is just an alias for v2.0
12:27:26 <edleafe> johnthetubaguy: ugh
12:27:33 <gmann_> also may be some dropdown thing for version etc.
12:27:45 <johnthetubaguy> v2.0 is the first version of our API, oddly
12:27:55 <johnthetubaguy> (well assuming you don't count the ec2 compat one)
12:27:59 <edleafe> johnthetubaguy: Oh, I remember the history
12:28:26 <johnthetubaguy> yeah, just making sure we all agree really
12:28:58 <gmann_> yup
12:29:05 * bauzas waves again super late and lurks
12:29:13 <alex_xu> yea
12:29:37 <johnthetubaguy> cool, seems like we have a bit of a docs plan forming there
12:29:51 <johnthetubaguy> alex_xu: did you check to see if all the issues on your etherpad are fixed now
12:30:01 <alex_xu> johnthetubaguy: not yet
12:30:05 <johnthetubaguy> alex_xu: it looks like the api-site repo has been updated to fix all those
12:30:15 <johnthetubaguy> alex_xu: is it OK to give you that action?
12:30:28 <alex_xu> johnthetubaguy: yea, it is ok for me
12:30:45 <johnthetubaguy> I can take the action to attempt some doc unification, and see what folks think in the docs side of the house
12:30:51 <alex_xu> #action alex_xu ceck to see if all the issues fixed on the v2.1 api doc
12:31:24 <alex_xu> #action johnthetubaguy take a look at more about doc unification
12:32:01 <alex_xu> any more actions?
12:32:26 <alex_xu> ok, so let's move on
12:32:31 <johnthetubaguy> that seems good, thank you
12:32:37 <alex_xu> #topic Mitaka planning
12:32:49 <alex_xu> #link https://etherpad.openstack.org/p/nova-api-mitaka
12:32:57 <alex_xu> I fill few items
12:33:16 <sdague> what bits of v3 are still out there?
12:33:19 <gmann_> alex_xu: Thanks
12:33:32 <alex_xu> please feel free add more and more detail for each item
12:33:47 <johnthetubaguy> so I have an idea of a possible focus area...
12:33:53 <alex_xu> sdague: we just deprecated, like APIRouterV3 still in the code, just left some cleanup work
12:34:04 <sdague> ah, gotcha
12:34:07 <gmann_> sdague: may be some v3 APIrouter and config options which we deprecated..
12:34:13 <gmann_> yea
12:34:16 <johnthetubaguy> ah, yeah, thats good to do
12:34:46 <johnthetubaguy> so my idea for focus is actually feature classification
12:34:59 <gmann_> remove extension? are we planning to do in M?
12:35:12 <johnthetubaguy> I have some notes on the idea here: https://review.openstack.org/#/c/215664/
12:35:13 <alex_xu> gmann_: I guess that need dicussion in summit
12:35:22 <gmann_> alex_xu: ok
12:35:30 <sdague> johnthetubaguy: sure, it feels like we should have a good docs story first
12:35:38 <sdague> but that seems like part of the doc story
12:35:40 <johnthetubaguy> basically feature classification would help us make sure we document and test everything we need
12:35:45 <johnthetubaguy> yeah
12:36:35 <johnthetubaguy> basically, its about joining up our CI tests, with tempest tests, and docs, so we know what features are "finished" for some definition of "finished"
12:36:39 * alex_xu will take a look at that patch to get what is that
12:36:58 <johnthetubaguy> so we say this API is tested, and its documented here
12:37:01 <gmann_> it looks interesting. i ll also look in detail tomorow
12:37:11 <johnthetubaguy> the other side of this, is that we take a user focused look at the API
12:37:22 <johnthetubaguy> (through the testing and docs work)
12:37:38 <johnthetubaguy> and that will help us work out what needs urgent attention so we are more interoperable, etc
12:37:45 <johnthetubaguy> and have a more usable API
12:37:59 <alex_xu> probably get, finish the coding, doc and test, then we can call it finished
12:38:03 <johnthetubaguy> the task work looks like it might be getting attention, and could eventually impact the API usability
12:38:24 <johnthetubaguy> alex_xu: thats pretty much it, along with "complete enough to be useful", should be in that doc
12:39:07 <sdague> right, up until this point the api doc and testing has been playing catch up to the code
12:39:07 <alex_xu> johnthetubaguy: ok
12:39:10 <gmann_> johnthetubaguy: how about adding use case of API in doc. we will have those in spec
12:39:15 <sdague> and now we'd like to invert that a bit
12:39:51 <edleafe> sdague: +1
12:39:57 <johnthetubaguy> yeah, at least, understanding the gaps, so people know what to work on
12:39:59 <gmann_> sdague: yea
12:40:29 <johnthetubaguy> gmann_: totally needs the usecase in the docs, I am thinking about migrate vs evacuate, as an example
12:40:56 <johnthetubaguy> gmann_: probably in the concept docs, and linked, but thats fine, all part of the story
12:40:56 <gmann_> yea
12:41:24 <johnthetubaguy> so, there is another idea that follow on from this...
12:41:36 <gmann_> and also link to spec too..
12:41:48 <johnthetubaguy> marking an API as experimental, until its fully tested and documenting, so its possible it would be removed, until that is complete
12:42:02 <johnthetubaguy> but I know that has problems
12:42:32 <alex_xu> sounds like we want to introduce 'experimental' back again
12:42:58 <sdague> honestly, I don't think experimental works
12:43:01 <johnthetubaguy> well, thats a separate conversation, but I think it would help make sure we get docs added, it would be nice to avoid that though
12:43:13 <johnthetubaguy> sdague: so now we have depends on, maybe we just don't need that
12:43:50 <sdague> but we do need a way to mark up which bits are tested and documented
12:44:07 <johnthetubaguy> yeah, anyways, something to think about
12:44:36 <johnthetubaguy> its the need to remove something if its never tested that worries me really, never been able to do that in the API
12:44:55 <johnthetubaguy> anyways, I think a docs focus is needed, as we didn't manage it this cycle
12:45:01 <sdague> right
12:45:09 <gmann_> yea
12:45:22 <johnthetubaguy> feature classification I think would help organise that effort somewhat (and leave us with handy docs for our users)
12:45:45 <johnthetubaguy> (PS it needs a better name!)
12:45:55 <bauzas> feature classification ?
12:45:58 <johnthetubaguy> yeah
12:46:27 <johnthetubaguy> anyways, lets not go there right now
12:46:37 <alex_xu> ok
12:46:43 <bauzas> johnthetubaguy: okay, let's discuss that off-topic
12:47:26 <alex_xu> so I think we needn't discussion each item in the etherpad today? when people think about more and fill more detail, then we can dicussion each item more in next few meetings, is that ok?
12:47:34 <sdague> if we set the goal as a solid API guide for mitaka release day, I think we'll all be really happy
12:47:41 <johnthetubaguy> +1
12:47:49 <johnthetubaguy> honestly, everything else is optional
12:47:58 <alex_xu> heh yea
12:48:08 <gmann_> yea +1 :)
12:48:24 <johnthetubaguy> really, I would love us to do no more API work until we have the docs done (mins the odd features folks push in)
12:48:58 <johnthetubaguy> I think JSON home is great, its just docs are more important right now (we might end up needing that for the docs, but thats a different thing)
12:49:19 <johnthetubaguy> what do people think?
12:49:28 <sdague> +1
12:49:36 <johnthetubaguy> I know its not very exciting, but our users need this to happen
12:49:38 <gmann_> johnthetubaguy: yea, we can add providing the req response scheme there
12:50:00 <sdague> yeh, it should be possible to write an application to Nova without reading the nova source code
12:50:01 <oomichi_> johnthetubaguy: +1 for doc. but I love still json-home
12:50:05 <sdague> today I don't think that's possible
12:50:16 <johnthetubaguy> sdague: very well put
12:50:57 <edleafe> yeah, docs are the biggest need by far
12:51:13 <alex_xu> ok, looks like we all agree on the doc is important
12:51:36 <johnthetubaguy> that means we don't do json home till its done, which hurts, but I think its the right call
12:51:53 <oomichi_> I hope the doc is auto-generated without human's hands as possible
12:52:14 <alex_xu> oomichi_: yea
12:52:16 <johnthetubaguy> oomichi_: we need real concept docs first
12:52:24 <johnthetubaguy> the hard stuff
12:52:31 <oomichi_> johnthetubaguy: +1 for the concept fist
12:52:37 <oomichi_> s/fist/first/
12:52:42 <johnthetubaguy> ideally we make sure swagger can do the right thing for us too
12:53:00 <johnthetubaguy> oomichi_: you still going to get that prototype ready for the summit?
12:53:16 <oomichi_> yeah, I am trying now.
12:53:19 <gmann_> johnthetubaguy: from json-home user can know the available features supported by cloud
12:53:41 <sdague> gmann_: sure, but unless they understand what those features mean, it's not super useful
12:53:44 <alex_xu> I'm also taking look at also
12:53:45 <gmann_> which will be runtime dicovery
12:53:54 <johnthetubaguy> gmann_: there are a whole heap of issues making that real, sadly (policy mostly), and yes, docs are more important right now
12:53:55 <sdague> I do get that's part of the discovery story
12:54:09 <gmann_> sdague: ye, totally agree after doc, we can do that stuff
12:54:24 <johnthetubaguy> gmann_: so docs will take all of us all cycle, I suspect
12:54:30 <johnthetubaguy> they are hard
12:54:30 <oomichi_> I tolk about it with mtreinish at qa-meetup, and it is fine to include it in tempest
12:54:31 <sdague> and, as johnthetubaguy said, there is this whole story around policy that needs sorted
12:54:46 <johnthetubaguy> so, the auto generation stuff
12:54:58 <johnthetubaguy> request validation stuff gives us the requests I guess?
12:54:59 <gmann_> hummm, yea. +1 after doc fix.
12:55:28 <johnthetubaguy> we have the API sample generation semi-auto stuff, does that get us all the responses already?
12:55:51 <sdague> they are in slightly incompatible formats
12:56:02 <sdague> some way to unify all that would be good
12:56:30 <johnthetubaguy> so my head is thinking... auto generate from code the docs, use those docs to test the API
12:57:10 <johnthetubaguy> oomichi_: are you things going that way?
12:57:14 * alex_xu warn the time is close
12:57:32 <oomichi_> we will be able to generate api doc from json-schema for response/request
12:57:45 <oomichi_> if migrating json-schema of response from tempest into nova
12:58:05 <alex_xu> 2 mins left
12:58:27 <oomichi_> I will explain it later on openstack-nova
12:58:29 <gmann_> yea, that's the final plan to have response one also in nova tree
12:58:49 <gmann_> as discussed in last summit..
12:58:49 <alex_xu> one more thing
12:59:01 <alex_xu> I will begin public vacation from tomorrow, will back until next Thursday. Appreciate if anyone can running the meeting next week.
12:59:10 <sdague> alex_xu: I can run it
12:59:15 <alex_xu> sdague: thanks a lot
12:59:24 <sdague> enjoy your vacation
12:59:28 <alex_xu> sdague: thanks
12:59:38 <alex_xu> so let's move the discussion to openstack-nova
12:59:48 <alex_xu> let's close the meeting, thanks all!
12:59:57 <alex_xu> #endmeeting