13:00:02 #startmeeting nova api 13:00:03 Meeting started Wed Mar 23 13:00:02 2016 UTC and is due to finish in 60 minutes. The chair is alex_xu. Information about MeetBot at http://wiki.debian.org/MeetBot. 13:00:04 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 13:00:07 The meeting name has been set to 'nova_api' 13:00:13 who is here today? 13:00:19 hi 13:00:20 o/ 13:00:23 hi 13:00:26 hi 13:00:26 o/ 13:00:29 hi 13:00:51 welcome everyone, let's start the meeting 13:00:57 #topic Nova Microversion testing in Tempest 13:01:05 gmann_: your turn first 13:01:14 ye 13:01:14 o/ 13:01:22 anyone have a link to the agenda handy? 13:01:32 annegentle: https://wiki.openstack.org/wiki/Meetings/NovaAPI 13:01:33 so all necessary patches are merged now. 13:01:37 ty! 13:01:54 framework is in tempest/lib and 2.2 tests are already running on gate 13:02:07 u2.10 and 2.20 are up 13:02:22 gmann_: cool, I guess just need some review on specific version test 13:02:35 so basically microverions tests can be implemented 13:02:36 yea 13:02:52 nice :-) 13:02:57 creating doc for those also 13:02:59 #link https://review.openstack.org/#/c/261426/ 13:03:13 oomichi_: Thanks for review. i updated that patch 13:03:24 woop woop doc :) 13:03:25 gmann_: ok, will review it again later 13:03:35 That's all from my side 13:03:44 gmann_: thanks for the works, really good progress! 13:03:53 annegentle: :) 13:03:55 alex_xu: npo 13:03:57 np 13:04:15 #topic API Doc 13:04:22 #link https://review.openstack.org/#/c/294078/ 13:04:32 * edleafe walks in late 13:04:47 sdague: Thanks, i saw the devstack patch for capping the max microversion for mitaka. 13:04:55 sdague: ^ I saw this in the agenda, so i start a separate topic for this, do you want to update something for this PoC 13:05:12 alex_xu: yeh, we wanted to talk about this a bit for where we're getting 13:05:28 I think this etherpad is probably a better link so far - https://etherpad.openstack.org/p/api-site-in-rst 13:05:52 also I invited karenb who has been working on fairy-slipper 13:05:58 hi 13:06:01 * annegentle waves 13:06:07 Last week I spent much of the week trying to see what it would look like to get our API docs over into RST more directly, plus a bit of structured content for things like tables 13:06:25 I just started to look at your patch 13:06:30 http://docs-draft.openstack.org/51/294151/4/check/gate-nova-docs/c2a264a//doc/build/html/rest_api/servers.html is an example of what the output looks like for the servers resource 13:06:44 * alex_xu poke oomichi_: we should have something similar with swagger also 13:06:50 * johnthetubaguy nodding with respect at the etherpad 13:07:03 karenb: yeh, it's kind of a mess of a patch stack, so appologies in advance, this was mostly just pushing forward to see where we could get to 13:07:23 I am a bit behind in understanding how this fits together 13:07:27 alex_xu: I think what we're finding though is swagger needs too much additional engineering to get an author/ publish workflow 13:07:29 the crux of this is - RST files that look like this - https://raw.githubusercontent.com/openstack/nova/e8afd02ca66a0801974ba2199c5323736c606257/doc/source/rest_api/servers.rst 13:07:41 ok, so how about I provide some common background 13:07:53 are you trying to automate the generation of parameter definitions 13:07:54 karenb: yeah sorry for the "oh geez context" 13:08:12 2 weeks ago I spent some time looking at swagger and how it would apply to a long standing api like compute 13:08:16 mostly sdague and my concerns are around ongoing maintenance 13:08:24 both of content and tooling 13:08:28 annegentle: yes 13:08:40 and the problem is that swagger (and raml) is an API design tool, that has the side benefit of a docs framework 13:08:42 sdague: yeah it's the legacy APIs that aren't a fit 13:09:06 however, if you don't start with swagger at your design, things like request parameter body is pretty rough to model 13:09:12 yes, agreed. there is some mismatch 13:09:21 karenb has dug in and yeah... 13:09:27 sdague: yeah, I know 13:09:29 sdague: yes 13:09:29 because it expects a pretty strict model definition for in: body fields 13:09:36 that we just don't have 13:10:07 however, the WADL stack we have today is definitely holding us back from having docs that people can use 13:10:29 oh for sure 13:10:37 sdague: wait, body just a json-schema, why we said it is rough to model? 13:10:40 adding microversion to WADL seem like a backwards step, so we need another route 13:10:42 so... could we have a nearish term solution of getting over to RST 13:10:52 sdague: I have another idea now, my prototype is trying to create swagger data from api router info instead of the code 13:11:00 alex_xu: it's not just jsonschema 13:11:13 sdague: https://review.openstack.org/#/c/296146/ 13:11:16 oomichi_: that's the idea for fairy-slipper too but the engineering burden is then high 13:11:17 json schema should be able to model the api, no? 13:11:33 karenb: parts of it, probably 13:11:36 karenb: at least the request/ responses in this case I believe 13:11:46 our jsonschema changes based on microversion though 13:11:47 (nova has those defined?) 13:11:50 sdague: ah ok 13:11:53 some of them 13:11:53 annegentle: yeah, we need to find a nice way to avoid it 13:12:30 and I am trying to create a prototype for action api which is most difficult api for us 13:12:33 anyway, I feel like the trap that WADL provided us was that we assumed that if we had some machine format, and a tooling pipeline, we end up with good docs 13:12:39 to avoid the big burden 13:12:46 but, it puts all the burden on the tooling pipeline 13:12:54 in json schema we can add description for each param etc but those are not yet complete info we can put there 13:12:55 the original idea for fairy-slipper was to automate making the reference info. however, in practice nothing was structured enough for "prose plus examples" I believe, and migrating showed us that. 13:13:02 and doesn't let humans realize that sometimes things have to be explained differently to make sense 13:13:13 oomichi_: right on the /actions POST, ack 13:13:14 there is very little human judgement on the output 13:13:20 my idea is to provide swagger definition from REST API directly 13:13:31 so, let's see what a content first approach looks like 13:13:35 so I think we need to have a concrete problems to focus on here, my choice would be: "how do we doc the microversions ASAP" and "how do we replace WADL quickly"? 13:13:40 like kurbenetes 13:13:42 sdague: +1 lets look at that 13:14:03 so, that would be RST that looks like this - https://raw.githubusercontent.com/openstack/nova/e8afd02ca66a0801974ba2199c5323736c606257/doc/source/rest_api/servers.rst 13:14:20 and you will notice there is a rest_parameters stanza 13:14:41 which is a list of parameters and types, that look up in a different file 13:14:51 have you determined that swagger cannot replace wadl for compute? 13:14:57 johnthetubaguy: nice point. I am thinking swagger definition of microversionscan be gotten easily if REST API 13:15:13 johnthetubaguy: because we can specify microversion on nova api 13:15:13 karenb: it can, but only with a lot of extensions and then we have toolchain maintenance 13:15:13 this is "just enough structure" to make generating tables in RST 13:15:40 oomichi_: also, these parameters.yaml files could be built from Swagger's parameters sections 13:15:50 oomichi_: I 100% believe that swagger on the compute API is a wild goose chase. You are going to need to hack up swagger way outside the spec to make it work 13:15:59 then you have to own an entire swagger publish toolchain 13:16:09 we do not have the engineering for that 13:16:14 sdague: in that rst, can we use json schema for pram definition ? 13:16:28 #link http://paste.openstack.org/show/491575/ 13:16:41 this is an example of some yaml pulled from a wadl migration 13:16:41 gmann_: maybe, it actually looks very much like what fairy-slipper was producing in the wadl -> swagger conversion 13:17:00 https://github.com/openstack/nova/blob/e8afd02ca66a0801974ba2199c5323736c606257/doc/source/rest_api/parameters.yaml 13:17:01 yeah 13:17:16 I snagged the in: idea from swagger 13:17:55 to me, this might be an ideal way to prioritize "more contributors by getting off of wadl" while still borrowing what we can from swagger 13:17:56 one idea is we generate swagger from code, and generate api doc like sdague's way 13:18:11 alex_xu: yeah but we've not got the engineering time for that 13:18:23 here is the thing, generating swagger from code is engineering effort beyond getting content to the user 13:18:34 alex_xu: I mean, I would love if we could generate parameters.yaml from code! 13:18:38 that would be really cool 13:18:45 so I like sdague's approach as it opens up more options for the future, gets us microversion docs, and kills the WADL issue 13:18:48 but swagger from code, not so much 13:18:52 my concern is what is the shortest path to get off WADL in a content first approach 13:18:56 annegentle: ah, yes, something like that 13:19:24 yeah, lets get some docs where we control the tooling better, then start iterating some improvements, I love it 13:19:27 and, because of the way we plug structured data into the RST with things like the rest_parameters stanza, that could clearly be swapped out later for other kinds of structured data 13:19:29 another merit of swagger is for client api also if we provide it with rest api 13:19:33 and I know this is a nova-centric meeting, but of course I have to be the voice of reason for "ALL THE APIS" and I'm okay with RST plus YAML instead of RST plus Swagger for the legacy APIs that don't fit the model well. 13:19:34 not only for doc 13:19:46 oomichi_: all of those are theoretical benefits 13:19:49 sdague: yes, and we won't generate another huge work for migating wadl to something else 13:19:52 oomichi_: yeah I know, but most people I talk to aren't huge fans of the generated clients 13:19:58 oomichi_: believe me, I've asked and asked 13:20:06 another thing this makes a bit harder is a "try it out" site 13:20:11 because client code also can be genereted from swagger definition via rest api 13:20:14 but again, we would need more engineering time 13:20:37 so the problem we have is all our new APIs have zero docs 13:20:38 oomichi_: that I think is the huge falacy that gave us WADL 13:20:44 RST gets us there real quick 13:20:48 WADL was used for the same assumptions 13:20:51 oomichi_: yes but not unless you use x-post (an extended definition) and then engineer all tools specifically for your extensions 13:20:58 and it turns out the consumers of our API docs are.... humans 13:21:00 do you plan on using the sphinx tools to generate html from the rst 13:21:02 WADL was used for filtering requests 13:21:03 and we are serving them well 13:21:10 karenb: yes 13:21:12 and we need something that does one thing not multiple 13:21:27 this is a normal sphinx pipeline from rst forward 13:21:31 karenb: yeah, there is a need for a sphinx extension to make nice tables from yaml 13:21:38 karenb: when sdague has created 13:21:49 annegentle: yeah, we need the docs, the other stuff we can worry about later 13:22:01 if you pull that nova branch and run tox -e docs, it will build this html locally 13:22:02 johnthetubaguy: agreed, outcome is developer.openstack.org that's useful 13:22:28 karenb: what I'd like to do this week is try to use the openstackdocstheme and better CSS for tables 13:22:42 but want to be sure we have agreement on the path in general of course 13:22:58 we'll also talk about it at the API WG meeting this week 13:23:42 right 13:23:50 annegentle: aren't there any projects which use swagger yet? 13:24:00 I think the important thing to focus on is how soon can we get real docs to our users 13:24:03 it feels like this is our only chance of getting good microversion docs by the end of the cycle, so it excites me 13:24:05 sdague: +1 13:24:07 oomichi_: magnum has a swagger file, but their API might be redesigned 13:24:21 annegentle: ah, ok. thanks for the info 13:24:30 oomichi_: and sahara has one generated with a pecan plugin I believe 13:24:40 do you have detailed docs on the use of microversions 13:25:00 I am not sure how that is related to your api model 13:25:25 oomichi_: we have a patch in progress to build the migrated swagger files 13:25:27 #link http://docs-draft.openstack.org/59/286659/9/check/gate-build-swagger/95e743a/swagger/compute-v2.1-swagger/index.html 13:26:01 annegentle: cool, thanks again :-) 13:26:04 karenb: what kind of info are you looking for? 13:26:09 karenb: I tend to point people at sdague's blog post: https://dague.net/2015/06/05/the-nova-api-in-kilo-and-beyond-2/ 13:26:17 yeh, that link is good background 13:26:30 karenb: and this is also one http://developer.openstack.org/api-guide/compute/microversions.html 13:26:32 and then there are details in the tree a bit on the ones we've landed 13:26:49 #link http://docs.openstack.org/developer/nova/api_microversions.html 13:26:54 what resources are available on what version, how do you access these versions, etc 13:26:59 ^^ yeah that one is for contributor devs 13:27:25 http://developer.openstack.org/api-guide/compute/microversions.html 13:27:47 oh wait, yeah, thats the same thing, the API user guide 13:27:54 ah, looks like we already have a lot of doc for microverions :) 13:28:03 :) 13:28:04 except for the user :) 13:28:18 sdague: this is for user http://developer.openstack.org/api-guide/compute/microversions.html 13:28:20 only one for the user and no reference info :) 13:28:38 yeah, no reference info yet, thats the aim here 13:28:42 but honestly, this is firstly about maintainable content 13:28:44 oomichi_: we will not that on http://docs-draft.openstack.org/59/286659/9/check/gate-build-swagger/95e743a/swagger/compute-v2.1-swagger/index.html doesn't have response parameters 13:28:46 yea 13:29:03 alex_xu: it's not, it doesn't tell them what's in the various microversions 13:29:17 sdague: yeah, nice point. 13:29:24 sdague: ah, I got it 13:29:32 oomichi_: and that's part of the findings as we got deeper into swagger... 13:29:42 what got us here won't get us there? Or something? 13:29:52 sdague: we need to migrate jsonschema from tempest if swagger 13:30:13 sdague: then the ownership of jsonshema discussion again.. 13:30:19 oomichi_: again, that's a whole lot of engineering effort before we ever actually solve any problems for our users 13:30:24 oomichi_: ah, yes, that is another huge work for support swagger :( 13:30:26 we have to be user centric here 13:30:39 right... 13:30:49 how do we solve that fact that anyone who wants to write an application with nova has to read the nova source code today 13:30:56 solve for that first 13:31:17 then look at ways we might optimize our storage / generation of some of that data 13:31:18 sdague: yeah, I know. maybe swagger thing is long-term work on nova. not so soon ;-) 13:31:31 oomichi_: yeah, that's my sense of it 13:31:58 but I also hope we can show json-schema in the doc, even with sdague's propose 13:32:12 alex_xu: as a phase 2, probably 13:32:12 alex_xu yea that will be nice 13:32:40 somehow it would be good to generate a schema to a specification whether swagger or something else 13:32:43 alex_xu: yeah I don't sense we're cutting off innovations there 13:32:48 it makes your api interoperable 13:33:04 karenb: yeah, and interoperability is needed for OpenStack DefCore 13:33:13 meeting the tests. 13:33:15 but here are tempest-cores also, it is not so hard :) 13:33:15 karenb: I agree 13:33:26 oomichi_: good :) 13:33:38 however, I want to make sure we don't get caught up on the schema before the user docs 13:33:49 current odc didn't tell user what is request and response format 13:34:20 sdague: yea, got it, step by step 13:34:31 s/odc/doc/ 13:34:42 as a for instance, just telling people 3 of the server parameters are only available in later versions of nova 13:34:45 sdague: but if we do schema thing later then would not it be duplicate effort to put all those param info in rst and yaml 13:35:16 http://docs-draft.openstack.org/51/294151/4/check/gate-nova-docs/c2a264a//doc/build/html/rest_api/servers.html#id5 13:35:16 and then ref those to schema 13:35:52 gmann_: we can either optimize for getting working docs, or optimize for data formats 13:36:13 maintainable docs 13:36:15 sdague: from schema ('required'), we can show the mandatory and optional param there 13:36:20 and I believe that if we optimize for working docs, we'll open up the api docs to new contributors that can help 13:36:21 (not arguing, heh) 13:36:46 instead of kicking them in the face with a pile of hard to understand sgml 13:36:58 humm 13:37:09 annegentle: if they aren't maintainable, they won't be working (for long) 13:37:21 aww sdague there are still over 100 contribs to the WADL each release, but yes we need to get off of it 13:37:38 annegentle: they are, and I commend their hero level of dedication to get there 13:37:55 one other Q I want to ask this group, is it easier in some ways to contribute to YAML and json schema files instead of RST due to English-as-a-second language? 13:38:32 I want to consider that many many contributors to the API reference don't mind it because it's like filling in a form. 13:38:41 swagger would have given us the "form" 13:38:48 but... the API doesn't quite fit. 13:38:59 does that make any sense or is it a needless worry? 13:39:06 annegentle: possibly, but at the end of the day you still need to write english on descriptions 13:39:14 English will always a problem, you need English explain the thing 13:39:20 sdague: so, so true 13:39:37 * alex_xu 's problem 13:39:51 alex_xu: yeah... I don't want to be inconsiderate of a big group of contributors here just because I write a ton 13:40:04 annegentle: it is easy to understand the code (json-schema, also) than English for me always :) 13:40:05 apart from english, i feel each developer like json nd yaml format(even with description than witting all in rst :) 13:40:14 gmann_: :) 13:40:25 oomichi_: me too :) 13:40:36 oomichi_: me too, sometimes :) 13:40:44 ok yeah... to me, this does mean it's worthwhile to eventually enable something like Swagger. 13:40:55 edleafe: when you ready my commit message 13:40:56 however, so far that has failed to make an API site that anyone would use 13:41:02 but! There's a ton of work on parameters.yaml to get those up to par 13:41:11 yeah I think this is a decent compromise 13:41:16 alex_xu: :) 13:41:23 annegentle: yeah, it is easy to understand api design from sample files actually 13:41:37 parameters.yaml should convert from wadl? 13:41:49 the body structures can be understandable from sample files 13:41:49 getting the content pieces right (req+response examples, params) is important 13:41:51 alex_xu: well, I'd like to find someone who would investigate 13:41:57 maybe it's sdague? 13:41:58 karenb: yes, absolutely 13:42:08 alex_xu: I would hope so 13:42:10 karenb: agree 13:42:12 maybe karenb can take a look? 13:42:36 I believe the fairy-slipper wadl -> swagger built content almost exactly like it 13:42:44 and we can tweak things to make that match 13:43:23 I need to look at parameters.yaml 13:43:32 this was an attempt to build a semi structured format that would be readonable to get over from our current bits 13:43:38 sdague: for now, parameters.yaml was just one idea right? 13:43:45 sdague: ok 13:43:50 so that the conversion could be quick 13:44:02 annegentle: yes, it's just the current thing I built that worked 13:44:04 sdague: yeah, I agree 13:44:11 wadl-> swagger has a model that is slightly different than swagger 13:44:15 if we need field changes in it, that's all negotiable 13:44:24 you could do anything with it 13:44:54 malleable! 13:44:55 karenb: yeh, annegentle showed me the json there and it looked really similar to https://github.com/openstack/nova/blob/e8afd02ca66a0801974ba2199c5323736c606257/doc/source/rest_api/parameters.yaml 13:45:41 and the content / structure of that file is just inside the rest_parameters sphinx extension, we can make it whatever makes sense 13:46:25 I also expect that the tools will get us about 90% of the way in a conversion, then we'll just have to clean up the final bits in a sprint 13:46:35 there will definitely be cleanup 13:46:44 but a sprint per project would get us there 13:47:16 sure. swagger2rst from fairy-slipper also creates custom rst directives and 13:47:37 collects the various rst pieces together 13:47:42 the parsing is not complicated 13:47:50 karenb: cool 13:47:54 karenb: oh yeah 13:48:53 (were there other agenda items?) 13:48:59 yes 13:49:06 yeh, we kind of monopolized here :) 13:49:11 ok didn't want to take over :) sorry 13:49:15 if we are cool for the doc, then we jump to open 13:49:27 sorry, but it was a big change in direction and wanted to get discussion going 13:49:42 yeah appreciate it all 13:49:49 sdague: yes, anyway we want to discuss newton work, the doc is part of that 13:50:15 #topic open 13:50:44 I think we didn't have time discussion other newton item today. Let us go through those next week 13:50:47 after discussion yesterday with sdague I've created this: https://github.com/cdent/microversion-parse 13:50:59 that might be relevant to some folk 13:51:00 cdent: thanks again for that 13:51:19 alex_xu: do you have the etherpad linke for newton api items? 13:51:21 it's pending infra-ness at https://review.openstack.org/296046 13:51:32 sdague: https://etherpad.openstack.org/p/newton-nova-api-ideas 13:51:48 johnthetubaguy also put something in https://etherpad.openstack.org/p/newton-nova-summit-ideas 13:51:49 we should put the standard header parsing as an item 13:52:07 sdague: microversion's header? 13:52:52 the new guideline on OpenStack-API-Version 13:53:04 sdague: ah, yea 13:53:12 sdague: it's in line 23 13:53:18 that's what cdent's library helps with 13:53:42 cdent: cool 13:54:18 cdent: looks interesting , will check in detail tomorrow. 13:54:30 thank alex_xu, gmann_ 13:54:35 thanks :) 13:54:53 so it will be candidate for all project's microversion header parsing right 13:55:05 gmann_: yes 13:55:06 i mean for api-wg 13:55:27 sdague: ok, will be good for tempest microversion testing too 13:55:38 if any people have real 'open' item, please bring up, otherwise you will lose the chance :( 13:57:11 ok, I guess no... 13:57:24 Kevin_Zheng: there is one https://review.openstack.org/#/c/293790/ I guess you put it here 13:57:36 yes 13:57:47 if there is still time 13:57:47 Kevin_Zheng: anything we can help? 13:58:00 Kevin_Zheng: sorry, 3 mins :( 13:58:18 yes last week I talk about your ideas about force stop instances 13:58:28 I put up a spec 13:59:12 Kevin_Zheng: ah, cool 13:59:36 I will try to reach that 13:59:37 Thanks, looks like you guys have alot of things important than this 13:59:47 yes, its not in a hurry 14:00:01 Thanks again 14:00:11 Kevin_Zheng: no worries, free to bring question at here 14:00:19 sorry, it's time to close the meeting 14:00:24 NP 14:00:29 thanks all! 14:00:31 #endmeeting