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