00:00:27 <etoews> #startmeeting api wg
00:00:28 <openstack> Meeting started Thu Jan 22 00:00:27 2015 UTC and is due to finish in 60 minutes.  The chair is etoews. Information about MeetBot at http://wiki.debian.org/MeetBot.
00:00:29 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
00:00:31 <openstack> The meeting name has been set to 'api_wg'
00:00:46 <etoews> anybody out and about for the api wg meeting?
00:00:47 <elmiko> o/
00:00:52 <ycombinator_> o/
00:00:59 <miguelgrinberg> hello
00:01:40 <etoews> #topic agenda
00:01:45 <etoews> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
00:01:53 <etoews> the usual agenda...
00:02:05 <etoews> #topic previous meeting action items
00:02:13 <etoews> #link http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-01-15-16.00.html
00:02:49 <etoews> is kaufer around?
00:03:05 <sigmavirus24> I'll check around
00:03:17 <miguelgrinberg> he did update his two specs, anyway
00:03:31 <sigmavirus24> Kaufer's nick isn't registered so I can't check in the usual way
00:04:02 <etoews> i see he added the cross project liaisons to his review https://review.openstack.org/#/c/145579/
00:04:21 <sigmavirus24> Yep
00:04:30 <etoews> no reviews from the CPLs though
00:04:32 <etoews> :(
00:05:11 <etoews> not a huge surprise. looks like CPLs are mostly the PTLs and are probably ridiculously busy.
00:05:40 <etoews> how do we entice projects to review guidelines that will impact them?
00:06:03 <salv-orlando> etoews: the previous weeks have been quite busy also for non ptls - sorry
00:06:39 <sigmavirus24> etoews: fwiw, the cross-project meeting was also cancelled this week. Maybe we should add this to the agenda for next week's meeting?
00:07:13 <sigmavirus24> I'm probably going to be at it either way so I can represent our interests there if you or kaufer cannot make it
00:07:43 <etoews> i confess i'm not familiar with the cross-project meeting. link?
00:08:30 <salv-orlando> In my experience the cross-project meeting now have more of a project/release management flavor to it
00:09:14 <sigmavirus24> salv-orlando: Ah, I haven't been to one before
00:09:14 <salv-orlando> Personally I think the most valuable method of reaching out and soliciting interest are 1) the mailiing list 2) chasing people on irc
00:09:26 <salv-orlando> with the latter more expensive of course
00:09:32 <sigmavirus24> etoews: https://wiki.openstack.org/wiki/Meetings/CrossProjectMeeting
00:09:49 <sigmavirus24> s/expensive/expensive & annoying/
00:10:35 <salv-orlando> sigmavirus24: there is also lazy consensus... you don't have to expect all CPLs to review
00:10:44 <sigmavirus24> yep
00:11:26 <salv-orlando> still no CPL is not good!
00:11:42 <etoews> true. but coming to them down the road and saying you should follow this guideline and they say "where did that come from, i'd never agree to that" is not a good place to be.
00:11:44 * sigmavirus24 just annoyed the nova PTL for fun and profit
00:12:17 <etoews> let's at least try to get a bit more engagement from the project teams.
00:12:19 <sigmavirus24> Oh, for what it's worth, glance is already implementing Kaufer's spec on sorting
00:12:29 <salv-orlando> One more thing, that I noticed recently... I did not have the "api" topic in my ML filters. Perhaps a public invite to all CPLs, PTLs and various core team members caring about the API to do this won't harm
00:12:30 <sigmavirus24> So you can take that as a tacit/implicit +1 from us
00:12:53 <sigmavirus24> salv-orlando: we've invited them in the past but I suspect reiterating it wouldn't hurt
00:13:22 <salv-orlando> sigmavirus24: sure. Since I did not had the filter I missed the first invite!
00:13:38 <sigmavirus24> Heh, yeah
00:13:55 <sigmavirus24> Is that an action for etoews? Reinvite all teh cores
00:13:57 <etoews> i'm going to put something on the cross-project meeting agenda and attend the next one.
00:14:03 <sigmavirus24> etoews: +1
00:14:57 <etoews> #action etoews to put api wg item on the cross-project meeting agenda and attend the next meeting
00:15:13 <ycombinator_> Not sure if a matrix of projects' APIs vs. compliance with API-WG guidelines would act as a motivator
00:15:45 <ycombinator_> also apologies if this was already discussed in earlier meetings; I've missed quite a few
00:15:53 <miguelgrinberg> ycombinator_: that's a good idea
00:16:07 <etoews> that's an interesting idea. are we there yet?
00:16:10 <miguelgrinberg> we need to merge a bunch of guideline docs first, though
00:16:16 <etoews> exactly
00:16:27 <salv-orlando> ycombinator_: it would if somehow we manage to find a way to automate its generation and add it as part of gate jobs ;)
00:16:30 <etoews> i'm trying to envision it and it's looking pretty sparse.
00:16:39 <miguelgrinberg> let's call it the "API-WG" wall of shame :-)
00:16:40 <ycombinator_> it would be sparse at first
00:16:51 <ycombinator_> but I'm hoping the sparseness will be a motivator too :)
00:17:06 <etoews> salv-orlando: well that escalated quickly :)
00:17:32 <elmiko> i agree we definitely need to merge more guidelines before the wall of shame appears
00:17:44 <ycombinator_> +1
00:17:48 <sigmavirus24> miguelgrinberg: let's not
00:17:52 <miguelgrinberg> awesome, the name stuck ;-)
00:17:56 <sigmavirus24> damnit
00:17:57 <elmiko> but yea, i'm -1 on "wall of shame"
00:18:06 <sigmavirus24> ==elmiko
00:18:08 <elmiko> sorry
00:18:16 <sigmavirus24> no need to apologize to me
00:18:25 <etoews> seems we're agreed it's a good idea but maybe not just yet.
00:18:38 <etoews> let's see...miguelgrinberg to turn https://review.openstack.org/#/c/130715/ into a guideline
00:18:54 <elmiko> yea, it sounds great. i'm curious how much work it will be to analyse the various projects?
00:18:57 <miguelgrinberg> yeah, I did look at the json-home spec, but couldn't find any real world usage of it
00:19:08 <miguelgrinberg> and on top of that I do no like that spec
00:19:24 <miguelgrinberg> the only useful links point to our Keystone implementation, which is incomplete as far as I can see
00:19:40 <miguelgrinberg> they implemented the server, but the client does not use the json-home info
00:19:46 <miguelgrinberg> so it's really there, but unused
00:20:36 <miguelgrinberg> json-home does not seem to have much traction in the REST world, as far as I can see
00:20:52 <sigmavirus24> Well it was an IETF draft that expired
00:21:17 <miguelgrinberg> I fail to see its usefulness to be honest, so I can't write a guideline doc for it
00:21:23 <sigmavirus24> I expect it expired due to bikeshedding and Mark Nottingham's already busy life as chair of httpbis
00:22:04 <sigmavirus24> I think elmiko and I were the two people more excited about Keystone using json-home, so maybe one of us should take a crack at it?
00:22:22 <sigmavirus24> But I'd rather not have either of us put effort into it if the other WG members aren't interested in it
00:22:33 <elmiko> i don't think it was me, i'm not that familiar with json-home
00:22:40 <miguelgrinberg> maybe. I really like to understand how it helps.
00:23:00 <miguelgrinberg> I was hoping to find a client implementation that uses this, but there isn't one
00:23:09 <sigmavirus24> miguelgrinberg: is that a challenge? =P
00:23:20 <miguelgrinberg> why not? heh
00:23:44 * sigmavirus24 frequently implements obscure RFCs and drafts
00:23:45 <ycombinator_> miguelgrinberg: FWIW, we recently tried to implement a bunch of language bindings for OpenStack Poppy, which uses a JSON-home document; the SDKs did not find any use for it
00:24:17 <miguelgrinberg> ycombinator_: is there any code I can see that uses json-home to navigate an API? I did not find anything in or out of openstack
00:24:18 <ycombinator_> SDKs == language bindings (I realized I switched terminology there)
00:24:43 <sigmavirus24> ycombinator_: how close were you keeping to the design of the existing SDKs?
00:25:03 <ycombinator_> miguelgrinberg: not that I know of; I was +1ing your (lack of) findings with some evidence
00:25:06 <miguelgrinberg> to me json-home not only does not solve any problem, but also promotes breaking hateoas
00:25:07 <ycombinator_> sigmavirus24: fair point, very close
00:26:13 <sigmavirus24> ycombinator_: yeah the existing SDKs are kind of not designed for any kind of dynamism in how they interact with each other
00:26:21 <etoews> seems like adopting json-home would require a "new thinking" when designing/implementing a client.
00:26:38 <sigmavirus24> A looser design of an API could easily take advantage of json-home if it's as easy to implement as I think it might be
00:26:42 <etoews> hence the lack of real world client exmamples?
00:26:43 <sigmavirus24> etoews: right
00:27:10 <sigmavirus24> etoews: possibly. I think json-home, having expired as an RFC, also lost steam but I haven't looked at the httpbis mailing list archives for context
00:27:42 <etoews> sigmavirus24: so do you want to do something with this?
00:27:45 <sigmavirus24> It's entirely plausible that the jsonapi/hypermedia APIs movement around the same time discouraged Mark Nottingham
00:27:47 <etoews> (we should move on)
00:27:48 <sigmavirus24> etoews: maybe
00:27:56 <sigmavirus24> I'm not invested in it
00:28:07 <etoews> let's set it aside for the time being.
00:28:41 <miguelgrinberg> yeah, I think it is not something we can act on right away
00:28:46 <etoews> i did some preliminary analysis on the status vs state current design
00:29:02 <etoews> #link https://wiki.openstack.org/w/index.php?title=API_Working_Group/Current_Design/State_vs_Status
00:29:33 <etoews> it's just a start
00:29:56 <miguelgrinberg> so it's close to a tie
00:30:09 <elmiko> etoews: nice start!
00:30:52 <etoews> i want to get better at carving up the wadls for api analysis.
00:30:59 <miguelgrinberg> looks like state is commonly appended to a target object, but status is used mostly on its own. Interesting.
00:31:21 <elmiko> etoews: have you thought about injesting them into python objects, maybe easier to interrogate?
00:31:29 <etoews> miguelgrinberg: interesting. i hadn't noticed that.
00:32:05 <etoews> elmiko: do you know of a good python wadl parser or were you thinking just use an xml parser?
00:32:28 <elmiko> etoews: i saw one, lemme see if i can dig it back up
00:32:35 <etoews> either way. first i need to knock the rust off of my python skills. ;)
00:32:43 <elmiko> =)
00:32:47 <etoews> something i'm planning on doing anyway. :)
00:32:57 <ycombinator_> etoews: teh google turned this up: https://pypi.python.org/pypi/wadllib/1.1.4
00:33:59 <miguelgrinberg> so I don't know if this was discussed, but to me, "state" indicates one of possibly few expected operational situations, while "status" indicates something higher level, for example, if the entity is operating or not
00:34:36 <etoews> miguelgrinberg: have you read this? http://openstack-dev.openstack.narkive.com/UbM1J7dH/horizon-all-status-vs-state
00:34:37 <miguelgrinberg> so you would use "status" to indicate if a service is up or down, for example. And if the service is up, then you can query in which "state" it is in.
00:34:37 <elmiko> etoews: what ycombinator_ said, also i was looking at https://pypi.python.org/pypi/wadl2swagger/0.0.5 , swagger is just json, so a little easier to hack apart.
00:34:56 <miguelgrinberg> etoews: no, I have not!
00:36:17 <etoews> what bucket would a guideline about state/status belong in? http://specs.openstack.org/openstack/api-wg/
00:36:42 <etoews> Representation Structure Conventions?
00:36:55 <etoews> Naming Conventions?
00:37:15 <sigmavirus24> naming seems better
00:37:36 <etoews> sure. let's move on.
00:37:36 <ycombinator_> Terms?
00:37:53 <miguelgrinberg> we have a naming placeholder guideline, should it go there?
00:38:23 <etoews> miguelgrinberg: link?
00:38:31 <miguelgrinberg> https://github.com/openstack/api-wg/blob/master/guidelines/naming.rst
00:38:43 <miguelgrinberg> there's actually a TODO at the bottom for this
00:39:01 <etoews> ha. there you go.
00:39:03 <etoews> #topic APIImpact
00:39:17 <etoews> #link https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z
00:39:51 <etoews> anything anyone want to point out?
00:41:03 <miguelgrinberg> https://review.openstack.org/#/c/134279/4/specs/kilo/approved/server-count-api.rst
00:41:37 <miguelgrinberg> I like this. Maybe we should think about a guideline, to accompany the sorting, etc.
00:41:58 <sigmavirus24> miguelgrinberg: there is one
00:42:03 <sigmavirus24> Kaufer submitted one today I think
00:42:12 <miguelgrinberg> awesome, always a step ahead!
00:42:56 <sigmavirus24> It's already been through a couple revisions too
00:43:20 <etoews> include_count=1
00:43:37 <etoews> is there any guideline around representing boolean values:
00:43:39 <etoews> ?
00:43:43 <sigmavirus24> Not yet
00:43:46 <sigmavirus24> I was going to suggest that too :)
00:43:53 <etoews> include_count=1 or include_count=yes or include_count=true
00:43:58 <sigmavirus24> als y
00:44:00 <sigmavirus24> *also
00:44:17 <etoews> y instead of yes. you just triple your productivity.
00:44:24 <sigmavirus24> technically they're doing it right ("be liberal in what you accept")
00:44:55 <sigmavirus24> I just wish nova would stop sending every parameter they can think of on every api request it makes so other project's schema wouldn't need to accommodate them
00:45:14 <elmiko> lol
00:45:54 <etoews> sigmavirus24: did you want to propose a guideline?
00:46:17 <sigmavirus24> Why not
00:46:47 <etoews> #action propose guideline on representing boolean values
00:46:56 <etoews> this is interesting https://review.openstack.org/#/c/148037/
00:47:04 <etoews> "Let's sync with the API WG on the best (most consistent) way to do this."
00:47:47 <elmiko> that's nice to see
00:48:03 <sigmavirus24> very encouraging
00:49:01 <etoews> hmmm...i wonder why Qiming Teng didn't reach out to us.
00:49:27 <etoews> i need to understand nova microversion better...
00:49:51 <ycombinator_> also possibly related to this is how neutron v2 is doing versions
00:50:01 <ycombinator_> http://developer.openstack.org/api-ref-networking-v2.html (see GET /)
00:51:00 <etoews> so the broader problem is solve api versioning for openstack?
00:51:33 <etoews> what's the action item here?
00:52:01 <elmiko> the yaml implementation for the backend seems a little out of scope for api-wg
00:52:46 <ycombinator_> action might be to propose a guideline for version discovery and negotiation?
00:53:14 <elmiko> ycombinator_: do you mean discovery as in endpoint?
00:53:31 <ycombinator_> yes, how does a client discover all supported and current versions of a service
00:53:39 <elmiko> got it, +1
00:54:34 <etoews> ycombinator_: do you want to kick off a discussion on the ML?
00:55:02 <ycombinator_> sure, but I'll need a few days to research; I think there are several specs for this out there in openstack already
00:55:04 <miguelgrinberg> ycombinator_: doesn't this tie back to the json-home thing?
00:55:11 <miguelgrinberg> discovery is going to be hard to agree on
00:55:18 <ycombinator_> miguelgrinberg: I suppose it does
00:55:22 <ycombinator_> yeah, this is a hairy one
00:55:23 <sigmavirus24> it does
00:55:59 <etoews> so important to get this one consistent as it's one of the first things clients with stumble on.
00:56:21 <ycombinator_> this also ties into catalog structure, if that's something we want to take up
00:56:29 <etoews> #action ycombinator_ to kick of discussion on openstack-dev on how does a client discover all supported and current versions of a service
00:56:38 <etoews> ycombinator_: yes
00:56:50 <etoews> https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Service_Catalog
00:56:54 <ycombinator_> thanks
00:56:59 <etoews> needs analysis
00:57:10 <etoews> #topic guidelines
00:57:16 <etoews> #link https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
00:57:28 <etoews> dammit. it happened again. no time for the guidelines. :(
00:57:38 <etoews> i'm changing the order.
00:57:47 <elmiko> definitely need to bump it up the stack
00:57:57 <etoews> guidelines before apiimpact
00:58:06 <elmiko> +1
00:58:32 <sigmavirus24> heh
00:58:43 <sigmavirus24> also tell me to shut up more often
01:00:22 <etoews> the guideline https://review.openstack.org/#/c/137490/ from miguelgrinberg is possibly looking mergable.
01:00:31 <etoews> aaaaaand time.
01:00:37 <etoews> #endmeeting