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