16:00:23 <etoews> #startmeeting api wg
16:00:23 <openstack> Meeting started Thu Mar 12 16:00:23 2015 UTC and is due to finish in 60 minutes.  The chair is etoews. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:24 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:00:27 <openstack> The meeting name has been set to 'api_wg'
16:00:33 <annegentle> o/
16:00:40 <etoews> hello annegentle
16:00:44 <dtroyer> o/
16:00:53 <kaufer> hello
16:01:15 <elmiko> yo/
16:01:25 <miguelgrinberg> hello
16:01:33 <sigmavirus24> o/
16:01:49 <cdent> o/
16:02:01 <annegentle> agenda link?
16:02:04 <etoews> #topic agenda
16:02:13 <etoews> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
16:02:25 <annegentle> heh I'm first
16:02:44 <etoews> #topic JSON schema in WADL for http://developer.openstack.org/api-ref.html
16:02:56 <etoews> #link https://review.openstack.org/#/c/158348/
16:03:03 <annegentle> thanks etoews
16:03:21 <etoews> wanna give us a run down annegentle ?
16:03:23 <annegentle> I don't know how much more introduction is needed, but I wanted to bring a use case to this group to get input
16:03:32 <annegentle> basically, we now use WADL to create http://developer.openstack.org/api-ref.html
16:03:50 <annegentle> Those WADLs have... okay some of the WADLs have schema in XSD format.
16:04:03 <cdent> is that WADL hand made ?
16:04:13 <annegentle> the schemas aren't complete, but they do tell us what parameter types are expected
16:04:46 <katco> annegentle: sorry this is my first meeting, can i add something?
16:04:56 <annegentle> cdent: yes, and hand maintained, so that the service code doesn't get changed out from under us
16:05:15 <elmiko> i'm really curious about the WADL too, i've been wanting to do something for sahara but i thought there were plans to move away from WADL for the api-ref page?
16:05:21 <annegentle> cdent: they can be generated, sure, but then shouldn't be autogenerated all the time, so that app devs can rely on the "contract"
16:05:21 <etoews> annegentle: hand maintained by who?
16:05:58 <annegentle> etoews: Not very many people. Stats: http://stackalytics.com/report/contribution/api-site/90
16:06:14 <cdent> annegentle: I wasn't suggesting they should be auto-generated, just was curious how they were generated, as I have tried to use them to auto-generate gabbi tests and had some issues as well.
16:06:16 <annegentle> katco: sure, there's gonna need to be a lot of background looks like
16:06:22 <annegentle> cdent: ah ok, sure.
16:06:33 <annegentle> cdent: you can see the maintenance is tough :)
16:06:37 <cdent> :)
16:06:59 <elmiko> annegentle: has there been any further talk of moving away from WADL?
16:07:03 <katco> so i just wanted to clarify; the docs do a great job at generating a human readable site that hints at what parameters are needed, but in terms of semantic structure, it doesn't outline the actual format expected
16:07:15 <etoews> annegentle: IMO the maintenance should be on the project teams for the raw schema info
16:07:20 <annegentle> elmiko: yes, I'd like to next release, but there is no resource assigned to that now
16:07:32 <annegentle> katco: yes, agreed.
16:07:40 <elmiko> annegentle: ack, thanks. i'd really like for sahara to participate in api-ref
16:07:57 <annegentle> katco: some of the struggle is in "human-readable or contract-based"?
16:08:12 <annegentle> elmiko: great, you got my bug and request then?
16:08:25 <katco> annegentle: i don't think the two are mutually exclusive
16:08:29 <etoews> elmiko: do you think sahara would be willing to be an early adopter (guniea pig) for whatever comes after WADL?
16:08:46 <elmiko> annegentle: i don't think i saw it, refresh?
16:08:49 <annegentle> elmiko: oh it was to Sergey, sorry https://bugs.launchpad.net/openstack-api-site/+bug/1430860
16:08:50 <openstack> Launchpad bug 1430860 in openstack-api-site "Sahara project does not have API docs on the API Reference page at http://developer.openstack.org/api-ref.html" [High,Confirmed]
16:09:02 <elmiko> etoews: i think it's a real possibility. i'd be happy to help on the effort
16:09:08 <elmiko> annegentle: no worries =)
16:09:53 <elmiko> etoews: just as an aside, i did generate swagger for sahara so i think that's a step in the right direction for whatever format we end up moving to
16:10:02 <annegentle> elmiko: cool
16:10:30 <elmiko> annegentle: also, i've started a project to help generate swagger for pecan based apps as well
16:10:32 <annegentle> elmiko: my recent request is due to sahara being included in the "big tent" but not having required API reference
16:10:44 <annegentle> but we are digressing off topic, is that enough background info?
16:10:55 <elmiko> annegentle: ack, thanks!
16:11:15 <annegentle> knowing we are going off of WADL but without a true timeline with deadlines, katco went ahead and made JSON Schema fit into the WADL
16:11:20 <annegentle> for Block Storage API
16:11:22 <cdent> I would prefer to see us move to a modern format (like swagger) instead of further relying upon (and confusing-up) the WADL
16:11:37 <elmiko> cdent: +1
16:11:48 <cdent> However, given the lack of timeline, that may not be practical.
16:11:58 <annegentle> cdent: sure, but what about the timeline? should people wait another six months (minimum)
16:12:02 <cdent> :)
16:12:03 <annegentle> cdent: right
16:12:26 <etoews> cdent: +1 OTOH most of it wouldn't be wasted effort. the json schema can be reused in swagger (or whatever)
16:12:48 <cdent> yeah, if katco has already done the work, why not use it?
16:13:38 <annegentle> my guess is we wouldn't get full json schema coverage (unless katco is really really amazing) :)
16:14:14 <katco> annegentle: well i certainly plan on doing so for cinder
16:14:16 <cdent> we dont need to require parity do we: it's an added bonus where it is provided
16:14:16 <annegentle> and that was Jon's difficulty
16:14:28 <katco> annegentle: we'll see what my team's appetite is for the rest of openstack :)
16:14:36 <annegentle> katco: right :) it's a lot
16:15:31 <katco> annegentle: well when you're maintaining an sdk...
16:16:27 <annegentle> so my thought was to bring it to this group, for arbitration? Mediation? Meditation? :)
16:16:31 <annegentle> Guidance really.
16:16:41 <etoews> katco: right. it's a huge effort on the doc side but that saves a ton of effort times the number of sdks being supported
16:17:06 <katco> etoews: definitely
16:17:52 <annegentle> katco: what also gave me pause was that Jon is also working on a Go SDK -- so if he was hesitant, what did that mean?
16:18:01 <annegentle> since I'm no SDK dev
16:18:24 <katco> annegentle: i don't know, i don't know why additional information would hinder his progress
16:18:31 <annegentle> I just play one on TV, er stayed at a Holiday Inn last night, er.
16:18:37 <katco> lol
16:18:37 <elmiko> lol
16:19:10 <annegentle> generally speaking is consistency across all OpenStack APIs a requirement for gaining trust in the info provided?
16:19:29 <annegentle> perhaps that's the heart of this... that people don't know if they can trust upstream?
16:19:37 <annegentle> cdent: might have an opinion based on what you saw
16:20:00 <cdent> I'm no sure I understand the question?
16:20:00 <etoews> annegentle: in terms of the accuracy of the api doc?
16:20:37 <annegentle> etoews: in terms of accuracy which in this case extends to machine readability
16:20:54 <annegentle> etoews: as in, should the upstream doc offer machine readability at all
16:21:11 <cdent> ah. my very first expectation was for strict accuracy, but was quickly disabused of that notion...
16:21:18 <annegentle> cdent: if you couldn't do what you needed machine-wise with the upstream WADL then perhaps they are meant for human eyes only.
16:21:48 <katco> isn't machine readability the point of wadl/swagger/etc.? it's how the documentation site is generated after all
16:22:00 <cdent> Yeah, that's the conclusion I reached, but it would have been helped by having that stated explicitly
16:22:05 <cdent> (if it already is, I missed it)
16:22:32 <annegentle> katco: cdent: ok then the next question is, are the machines going to have to read only XSD for now until we get our timelines in place for swagger
16:22:51 <annegentle> katco: (does that accurately encapsulate the difficulty, that your machines can't read XSD?)
16:23:05 <katco> annegentle: i can support whatever format you find most agreeable; what's important to me is only that the information is present in any format.
16:23:08 <cdent> I defer to katco: i satisfied my needs (for now), by hand :)
16:23:24 <annegentle> cdent: in what format did you make those in?
16:23:37 <katco> i would sort of like to stick with the work i've already done if possible though :)
16:24:02 <cdent> I was trying to auto-generate tests from the WADL when I realized I couldn't do that, I wrote the tests by hand, using the HTML output by the WADL as a guideline.
16:24:03 <elmiko> even if we migrate to swagger, i have a feeling there will still be a need for hand hacking some information in
16:24:20 <annegentle> cdent: ah ok
16:24:34 <annegentle> cdent: so the WADL and XSD was still the "source of truth"
16:24:40 <ryansb> elmiko: yeah, that's somewhat expected, and (IMO) swagger is a bit easier to hand-hack
16:24:51 <elmiko> ryansb: agreed
16:24:54 <annegentle> honestly I'm fine with accepting the patch as-is -- it's community doc after all.
16:25:08 <annegentle> but consistency and re-use and trust are of course needed.
16:25:14 <cdent> annegentle: I'd have to say _a_ "source of truth" that got me started, but was not complete
16:25:39 <annegentle> cdent: and incompleteness is also unfortunately a side effect of "community doc"
16:25:56 <cdent> yeah, and something I understood from the start
16:26:09 <annegentle> ok
16:26:21 <annegentle> don't want to take up all meeting time with the topic, but thank you all for the input.
16:26:30 <annegentle> If you could vote on the review itself, that'll help a lot!
16:26:34 <etoews> annegentle: can we call it an experiment? have a look at the results of whatever consumes that json schema before going all in?
16:27:22 <katco> etoews: ask and ye shall receive :) https://github.com/katco-/goose/blob/cinder-support/cinder/autogenerated_client.go
16:27:24 <annegentle> katco: can you link to go goose
16:27:28 <annegentle> :) yes thank you
16:27:47 <annegentle> etoews: yep definitely want to experiment!
16:27:47 <katco> etoews: that is 100% generated code from https://github.com/katco-/wadl2go
16:28:07 <cdent> what a _fanstastic_ name
16:28:09 <cdent> (goose)
16:28:10 <etoews> katco: wadl+json schema?
16:28:27 <elmiko> katco: neat!
16:28:30 <katco> etoews: yes; however, wadl is the driver
16:28:39 <katco> etoews: it could support xsd, xml schema, etc. etc.
16:28:45 <katco> elmiko: ty!
16:30:00 <etoews> this definitely looks interesting. nice work katco.
16:30:17 <katco> etoews: ty, couldn't have done it with the support of this community
16:30:46 <etoews> annegentle: katco: thanks for bringing this up. i think the action here is for people who are interested to review https://review.openstack.org/#/c/158348/3
16:30:56 <annegentle> yes. thanks etoews!
16:31:06 <etoews> let's move on
16:31:26 <etoews> #topic errors
16:31:29 <katco> i need to run, but feel free to ping me here on freenode with any questions
16:31:35 <katco> thank you for your time!
16:31:40 <etoews> #link http://lists.openstack.org/pipermail/openstack-dev/2015-January/055570.html
16:31:45 <etoews> thanks katco
16:32:02 <etoews> so there was that extensive thread on errors
16:32:24 <etoews> i'd like to come up with a guideline for errors
16:32:40 <etoews> i'd probably use json schema to express it
16:32:48 <etoews> any thoughts on that?
16:33:18 <cdent> json schema seems right, was there resolution on the idea of codes within the message body (instead of just messages)?
16:33:40 * cdent kind of lost track of the thread
16:34:24 <elmiko> i wonder if any of the logging wg folks have weighed in on this as well. if we are going to define a schema for output it might be nice to see if they have any ideas.
16:34:42 <etoews> there was some intersection between the two
16:35:09 <elmiko> cool
16:35:19 <etoews> i'd like to decouple it as much as possible though. the error code could be the interface between the two. doesn't that make sense?
16:35:32 <etoews> s/doesn't/does/
16:35:39 <cdent> yes
16:35:56 <cdent> the point of the code is to allow (and limit to just) that kind of coupling
16:36:07 <etoews> yep
16:36:20 <etoews> and maybe some kind of "transaction id" too
16:36:24 <elmiko> makes sense
16:36:57 <elmiko> we added unique id's to the error messages in sahara recently, i think they are useful if there is a clear path on what to do with the ids
16:37:05 <cdent> isn't there already some kind of request id middleware thingie used in some of the projects (which would allow _it_ to be decoupled from _this_)
16:37:10 <elmiko> otherwise it's just another uuid to clutter up the log
16:38:08 <etoews> elmiko: ya. there needs to be a clear connect between the error response and what's going on in the log.
16:38:30 <etoews> once the guideline is ready i would definitely ask the logging folks to review.
16:38:37 <elmiko> nice
16:39:08 <etoews> #action etoews to create an error guideline
16:39:10 <elmiko> i'm not sure the best way to make that connection, but i've experienced some head-scratching moments trying to figure out what all these extra ids and codes are supposed to help with
16:40:03 <etoews> elmiko: i've got ideas in my head about that and need to get them out to see if the match up with anyone else's ideas about that
16:40:24 <elmiko> etoews: awesome!
16:40:29 <etoews> #topic versioning
16:40:45 <etoews> sigmavirus24: did you want to talk about this?
16:41:29 <rosmaita> if not, i added the subtopic
16:42:03 <sigmavirus24> I'll defer to rosmaita
16:42:29 <rosmaita> ok, suppose there is a project, not glance, that is considering adding some new functionality
16:42:34 <rosmaita> on a new endpoint
16:42:51 <rosmaita> and it's not completely clear that the api is right
16:42:52 <rosmaita> i mean
16:43:00 <rosmaita> it is right syntactically, restful and all that
16:43:11 <rosmaita> but may not expose all the right stuff for the purpose
16:43:21 <rosmaita> what would it mean if we called it EXPERIMENTAL
16:43:43 <rosmaita> what are our obligations about deprecation, etc
16:44:09 <rosmaita> that's basically it
16:44:11 <etoews> beta might be a better word but i get what you mean
16:44:33 <rosmaita> well, i was looking at the api ref, it's got current, supported and experimental
16:44:42 <etoews> ah
16:44:49 <elmiko> is there an X-DONT-EXPECT-TO-LAST header? ;)
16:45:03 <rosmaita> that could be arranged
16:45:08 <sigmavirus24> elmiko: +2
16:45:40 <elmiko> i like being able to have an experimental api, but i also know how experimental can quickly lead to production if too many people get used to it
16:46:04 <etoews> *wonders if there's any room for expressing "experiementalness" in nova's microversions*
16:46:11 <rosmaita> well, we think it's pretty much ready, but want it to get a workout
16:46:11 <dtroyer> so break it once in a while?
16:46:34 <miguelgrinberg> how about the traditional approach of not documenting what you don't want people to massively adopt?
16:46:37 <etoews> elmiko: definitely a valid concern
16:46:59 <rosmaita> miguelgrinberg: that also can be arranged
16:47:16 <sigmavirus24> jaypipes: has also had choice words to say about experimental APIs.
16:47:19 <etoews> miguelgrinberg: basically the approach to a "private" api
16:47:26 <sigmavirus24> I suspect if cyeoh were around he'd agree
16:47:47 <miguelgrinberg> right, you can expose undocumented endpoints to test the waters, then decide in a later release if they make it as a public endpoint or not
16:48:18 <etoews> rosmaita: would you have people willing to code to the undocumented endpoints to test them?
16:48:23 <rosmaita> rosmaita: we actually want it to be used, though
16:48:40 <rosmaita> etoews: i think the endpoints would have to exist in service catalogs
16:48:44 <TravT> Think of it like Nova extensions.
16:48:50 <dtroyer> I don't like the undocumented bit, that leads to undocumented production APIs.
16:48:56 <sigmavirus24> etoews: one would likely be tested by Murano
16:49:00 <elmiko> is this a case where increased usage of json-home would help to clear up what is experimental and what is not?
16:49:04 <TravT> there is code today in horizon that optionally exposes a feature if the extension is available.
16:49:22 <sigmavirus24> The other is desired by Horizon but Horizon will probably be less likely to adopt an experimental (undocumented) API
16:49:49 <sigmavirus24> TravT: difference between experimental and extension is that an extension is ostensibly production ready
16:49:58 <rosmaita> how about we doc it as experimental?
16:50:27 <rosmaita> we just want to hedge on whether we can introduce breaking changes
16:50:41 <dtroyer> it is up to the discipline of client-side devs to not make experimental APIs default…if they always require specific action to be used, there should be no surprises down the road
16:51:20 <elmiko> dtroyer++
16:51:22 <dtroyer> and it will be those devs (and their users) who feel the pain when things break because they did not follow that
16:51:54 <etoews> dtroyer: that's reasonable to me
16:52:14 <rosmaita> dtroyer: so are you saying it's ok to make a breaking change, it's buyer-beware?
16:52:28 <etoews> rosmaita: in terms of doc'ing it, i don't think these nova docs go far enough http://developer.openstack.org/api-ref-compute-v2.1.html
16:52:33 <dtroyer> for experimental, yes
16:52:38 <TravT> dtroyer: that makes sense and the experimental designation is just more of notification so developers know and can make an informed decision?
16:52:47 <dtroyer> it would still be nice to do the versioning thing though
16:52:52 <lakshmiS> dtroyer: +1
16:53:02 <etoews> all they say is EXPERIMENTAL but don't explain what it really means.
16:53:09 <rosmaita> etoews: yes, we would be much more explicit
16:53:17 <rosmaita> in fact, that's why i raised the question
16:54:05 <rosmaita> what about the header business?
16:54:25 <rosmaita> we are thinking experimental in K, will make a decision to finalize in L
16:54:32 <rosmaita> not sure a header will really help
16:54:37 <rosmaita> but maybe that was a joke
16:54:59 <elmiko> i'm not sure that it would help, just throwing it out there
16:55:19 <TravT> X-API-Status: Experimental
16:55:29 <etoews> rosmaita: and this would be for a new endpoint of an existing api or a new project/api altogether.
16:55:45 <elmiko> given that many apis use the version as the root, e.g. /v1/.... , couldn't we recommend using /experimental/... or similar? (or does this break too many wsgi servers)
16:55:56 <dtroyer> I'm not sure what a header adds if you already know the API is experimental by picking it out of the service catalog that way
16:56:04 <rosmaita> elmiko: that's an interesting idea
16:56:41 <TravT> or typically, you'd see v0.1
16:56:52 <dtroyer> or even use /x1/ or similar so you still follow the conventions of production
16:57:05 <elmiko> right, x1 is nice and short too =)
16:57:14 <rosmaita> works for me
16:57:29 <elmiko> then you would know from the endpoint in the service catalog what you are pointing at
16:57:34 <TravT> that seems nice and clean
16:57:43 <dtroyer> I think one of the keys is that while experimental, it should still mirror production practices
16:57:47 <TravT> and we don't have to upgrade keystone features to support it.
16:57:57 <rosmaita> dtroyer: no problem there
16:58:27 <etoews> hmmmm...so what's the path for going from experimental to production in terms of versioning?
16:58:48 <elmiko> that's a tougher question imo
16:58:56 <TravT> x1 become v1?  or x2.4 becomes v2.4?
16:58:57 <etoews> i somehow thought we were moving away from putting the version in the url
16:59:14 <dtroyer> TravT: that was my thinking, or start over at /v1
16:59:24 <etoews> e.g. nova using a header for it's versioning
16:59:36 <dtroyer> etoews: I'd love that, but if it will have one in production it should have one in exp...
16:59:46 <sigmavirus24> etoews: I'd love to move away from that
16:59:47 <elmiko> etoews: i had not considered that
17:00:01 <sigmavirus24> Accept headers for JSON APIs are the de facto standard mostly anywhere else
17:00:10 <etoews> looks like we'll have to continue in #openstack-api
17:00:23 <etoews> #endmeeting