00:00:36 #startmeeting api wg 00:00:37 Meeting started Thu Jan 8 00:00:36 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:39 Useful Commands: #action #agreed #help #info #idea #link #topic #startvote. 00:00:41 The meeting name has been set to 'api_wg' 00:00:54 a happy new year to all. :D 00:01:03 +1 00:01:32 i get the feeling we might be a bit light on api wg attendees this time 00:01:56 hi 00:02:01 hi! 00:02:07 hi 00:02:20 hello! 00:02:21 #topic agenda 00:02:27 #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda 00:02:56 no new topics so moving right along... 00:03:07 #topic previous meeting action items 00:03:20 #link http://eavesdrop.openstack.org/meetings/api_wg/2014/api_wg.2014-12-18-16.00.html 00:03:58 i'm still working on the barbican swagger 00:04:11 i didn't get to all of my action items either :( 00:04:29 sick, holidays, catching up, excuses, excuses. 00:04:33 etoews: I think we should carry them forward (especially the API definition ones) 00:04:34 i was going to just convert the wadl, but after talking about it with the barbican folks i want to move ahead on doing it programatically 00:04:46 sigmavirus24: +1 00:05:18 elmiko: as in programatically building it from the source code? 00:05:42 etoews: sorta yea, more like using the wsgi object created by pecan and dumping info from there 00:06:04 but my pecan knowledge is still growing, so it's taking longer :/ 00:06:04 hm. interesting 00:06:23 that's how i did it for sahara, but in that case we use flask 00:06:33 elmiko: how much of that wsgi object is going to be turned into documentation? 00:06:34 isn't this locking us into continuing with Pecan? 00:06:44 * miguelgrinberg hopes one day will move to Flask 00:07:01 * sigmavirus24 hopes we never use an April Fool's joke in production /kidding 00:07:17 sigmavirus24: for sure we could generate the skeleton docs for routes and methods, and probably schema too 00:07:18 sigmavirus24: I think I can read when you are kidding now, took me some time ;-) 00:07:30 sigmavirus24: things like descriptions might be more hassle, or might not be wanted 00:07:39 miguelgrinberg: well, sahara uses flask =) 00:07:45 elmiko: I guess I'm wondering if something like betamax could help generate data for the docs too 00:08:08 use betamax with a requests session and you have dumps of the request/response cycle for each request and then you can parse that JSON turn it into docs 00:08:14 but we're not generating docs. we're generating api definition. 00:08:16 it's an idea I've thought about but never worked with 00:08:26 etoews: ah, misunderstood the purpose. sorry 00:08:51 yea, this will generate a skeleton of all the routes and methods(and hopefully schema) 00:09:06 elmiko: just as a starting point right? 00:09:14 it's possible to pull description type info into the swagger doc as well, but i'm not sure that's desired 00:09:18 etoews: yes 00:09:47 ya. i'm hoping it's the api def that drives the development of the implementation. not the other way around. 00:10:20 etoews: in the end that would be awesome, but baby steps... 00:10:31 +1 baby steps. 00:10:37 okay that's a good point to carry over the action items. 00:10:45 #action etoews update the scope section of the wiki page and include api definition format 00:10:55 #action elmiko to generate swagger doc for barbican and commit to github somewhere 00:11:06 #action etoews start discussion about api def formats on ml 00:11:18 #action sigmavirus24 reply to discussion with benefits moz saw from using an api def format 00:11:44 on the plus side i did get to do some analysis of the metadata design before i got sick. 00:12:01 etoews: very good analysis, I might say 00:12:20 ya. i was hoping to get some feedback about it. 00:12:26 #link https://wiki.openstack.org/wiki/API_Working_Group/Current_Design/Metadata 00:12:33 so it made sense the way i laid it out? 00:13:04 etoews: I meant to go look at the Heat stuff, because I think metadata there does not mean the same thing 00:13:14 but I haven't investigated yet 00:13:15 it was mostly a lot of copy/paste and then squinting to see the patterns. 00:14:12 miguelgrinberg: ya. i noticed that too. from the analysis "The outliers are Orchestration's Software Configuration metadata which seems to describe a concept different from the other services notion of metadata and Object Storage's metadata which does everything with headers." 00:14:13 etoews: yeah that makes sense the way it is layed out (at least to me) 00:14:36 etoews: makes sense to me as well 00:14:51 cool. hopefully it catches on. 00:14:54 so I think we now use this document and throw darts at me guideline doc? 00:15:03 s/me/my/ 00:15:07 right 00:15:38 apologies for not having a chance to give that one a proper review yet. 00:15:52 I sided with nova mostly, except for the implementation of the POST 00:16:26 let's discuss it when we get to topic guidelines. 00:16:31 should we reconvene about metadata next week? 00:16:46 #topic APIImpact 00:17:01 #link https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z 00:17:41 seems APIImpact is catching on... 00:17:58 anything anyone want to point out? 00:18:39 I have a more general question. When I did a review I -1'd it. The cinder guys sort of did not like that 00:18:58 Should we stay out of it and just comment? 00:19:28 miguelgrinberg: would you mind linking us to that review/comment? 00:19:41 that's a bummer... 00:20:49 looking for it, but it was a few weeks ago. It was not direct, I just felt they wanted to get moving, in spite of my recommendation 00:20:59 I withdrew my -1 00:22:05 i see 00:22:48 https://review.openstack.org/#/c/136253/ 00:22:48 My comment on Dec 11 00:24:56 i can see us running into this more and more in the near future. 00:25:06 Dave Chen brings up an interesting point about keeping their api internally consistent, i'm curious what the wg opinion should be on these things? 00:25:36 the projects will want to want to remain internally consistent even at the expense of being inconsistent with other projects 00:25:45 It's a tough one. At some point we need to break ties with the past. 00:26:01 Inconsistencies are inevitable in my opinion 00:26:28 i can certainly understand that point of view but we need people to start converging 00:26:34 I've never found a single API (in the world) that is entirely internally consistent 00:26:37 is there any action we can take to help smooth these transitions? (aside from providing a solid guideline) 00:27:03 I think for this it would have helped to have an official guideline, so I think we need to get them ready 00:27:15 that makes sense 00:27:36 ya. having a guideline we can clearly point to would carry much more weight 00:28:25 the only other carrot that comes to mind at the moment is pointing out other projects that are already following the guideline 00:28:50 that addresses Dave Chen's "it's not quite sure when will other projects formally follow the new style." 00:29:21 should be (I mean I) relax REST compliance and try to write guidelines that match something out there? 00:29:39 for metadata, my doc is almost matching nova 00:29:59 for sure you'll get much more traction that way. 00:30:19 i think as long as you're being pragmatic about it, it's for the best. 00:30:33 i like the idea of moving closer and closer to REST compliance 00:30:39 well, it's something we need to decide. Maybe turn a blind eye to small things. This one is a small thing IMHO. 00:30:44 etoews: +1 00:31:18 practicality beats purity 00:31:38 * sigmavirus24 spouts useless neologisms for irony and an appearance of wisdom 00:31:58 :) 00:32:01 lol 00:32:30 I wouldn't ignore these cases, but just a comment and move on… the comments will eventually add up 00:32:43 It's still confusing. Should new projects also be written following the almost RESTful guideline? 00:33:00 miguelgrinberg: that would be the ideal 00:33:02 or should we allow some sort of grandfathering for older projects? 00:33:19 but still recommend the best approach? 00:33:40 how about looking at it in terms of API revisions rather than whole projects? 00:34:02 although there isn't a compute v3 soon, that would have been the time to fix a lot of stuff, should we have the guidelines ready 00:34:29 same with sahara v2, we've talked about it at 2 summits now 00:34:55 miguelgrinberg: IMO new projects should be using the one-and-only guideline. 00:35:16 so we document the ideal solution, but mention the "close enough" solutions for legacy projects 00:35:35 to me that way lies madness 00:36:17 i think it would be confusing to new or existing api implementors. 00:36:35 i think what dtroyer is proposing would work 00:36:48 yes, if we start saying "do this", but if that is too odd for you then "do that", then we are going to lose credibility 00:37:13 yep. people will throw their hands up and walk away pretty quickly. 00:37:39 I think the "do this" part is sufficient…it'll be followed or not 00:37:47 rigth 00:37:52 +1 00:38:24 +1, but that leaves those who want to be consistent with old stuff out 00:38:41 basically we are saying join us or you're on your own 00:38:48 miguelgrinberg: at least it will provide a path to a possible new version though 00:38:49 but not for the next version of their api? 00:38:57 it leaves them where they are today already 00:39:01 etoews: true, only until the next rev 00:39:15 miguelgrinberg: I think the next large version of an API is really the best place to expect people to start to follow the guidelines 00:39:29 yeah, okay, I think I worry too much :) 00:39:40 miguelgrinberg: they're going to hate us no matter what we do 00:39:56 no no. it's really good to have these sorts of conversations early on in an effort like this. 00:40:02 we're potentially insulting their sensitive egos about the APIs they designed and we're telling them are now deficient in some respect 00:40:38 I think it will also save a lot of cross-project contention. I've seen people contributing to other projects get annoyed by having certain hacking checks disabled 00:40:49 sigmavirus24: that seems like it might be a problem with our communications as some level 00:41:15 sigmavirus24: some are always going to be that way…let them be, there are still plenty who are hungry for guidance and commonality 00:41:26 dtroyer: that's my point exactly 00:41:42 ah, not much we can do for those folks though? 00:41:57 snowflakes be snowflakes 00:42:02 lol 00:42:14 after 5 years, look at what projects still actively want to do things differently… 00:42:30 yep 00:43:10 FWIW, I'm fixing those at the language-binding and CLI levels… 00:43:34 at least someone's life is going to improve 00:44:02 dtroyer: applying spackle. :) 00:44:25 okay. so we shoot for pragmatic REST...meaning REST but tempered with the current design where it makes sense. 00:44:52 is that a fair statement or too broad to be of value? 00:45:19 i dunno, that seems to leave the door open for exceptions moving forward. seems appropriate for current stuff though. 00:45:51 Thought: What about a migration path. vCurrent+1 = middle-ground, vCurrent+2 = perfect future 00:46:00 I think it is fair, we can always improve our guidelines to drive towards closer REST 00:46:04 I don't think we should leave the out…our out is that we're writign guidelines, not requirements 00:46:28 dtroyer: i like the way you put it 00:46:51 sigmavirus24: sounds interesting to me 00:47:01 right right. there was a reason we didn't call it "standards" in the first place. 00:47:18 elmiko: I'm not sure it's a good idea but it might make people more amenable to it 00:47:27 Of course that means results will be a lot longer off 00:48:01 sigmavirus24: understandable, but i feel like the conversation around that idea could produce some useful fruit in terms of actions projects can take 00:48:01 sigmavirus24: that might be the reality, but I don't think we should codify that in our work 00:48:16 Do we need to wait for two major revs? I'd say vCurrent+1 should shoot for compliance with our guidelines. 00:48:29 miguelgrinberg: right, that's what I *want* 00:48:37 Anyway 00:48:39 miguelgrinberg: in an ideal world, yes 00:48:41 I think we're wasting a lot of time on this 00:48:51 This is perhaps a better discussion for the mailing list 00:49:03 do i smell an action item? 00:49:50 sigmavirus24: do you want to give yourself an action item for kicking off a discussion on the ml? 00:49:53 elmiko: did you just volunteer? 00:50:07 sigmavirus24: hey, i'm already behind on my action ;) 00:50:30 me too. ;) 00:50:33 #action sigmavirus24 will start a discussion on the ML about migrating to API WG standards 00:50:40 etoews: is the reason I'm behind on mine =P 00:50:47 that's ture 00:50:53 s/ture/true/ 00:51:18 #topic guidelines 00:51:24 #link https://review.openstack.org/#/c/145579/ 00:51:36 * sigmavirus24 was waiting for this section the whole time =P 00:52:21 This seemed to spawn from a discussion on the ML surrounding how clients sort output from the API, I'm curious what people think of the spec 00:53:04 everything surrounding pagination would benefit greatly from analysis of current design. 00:53:12 repeating the same query string args? Isn't that looking for trouble? 00:53:17 miguelgrinberg: it is 00:53:30 * sigmavirus24 is glad he isn't the only one who caught that =P 00:53:31 etoews: I agree 00:53:34 Haven't seen this before, I'll comment on it later 00:53:47 practically every project does it and there are a bunch of inconsistencies. 00:53:59 i comment on it too about current design. 00:54:11 Further this will cause issues with python clients consuming this. 00:54:17 * sigmavirus24 knows. he maintains requests 00:54:34 yeah, I would use a single key with comma separated keys, for example 00:54:34 #action etoews to comment on https://review.openstack.org/#/c/145579/ about current design analysis 00:54:35 I've seen rubby clients have trouble with stuff like this too 00:55:15 does the suggestion for the CLI format make sense here too? ie, sort=key1:dir1,key2:dir2 00:55:26 dtroyer: it could work 00:55:36 While we still have time: 00:55:38 #link https://review.openstack.org/#/c/131736/ 00:56:10 I think this has a noble purpose but will cause a lot of problems if it were actually to be accepted and (to some degree) enforced 00:56:51 is that talking mainly about the URIs or about json objects passed as body as well? 00:56:55 he does not say specifically how to achieve that. Simpler JSON bodies? 00:57:22 curl is just another client 00:57:33 not one that is specifically friendly to APIs 00:57:50 JSON is hard from the cmd line 00:57:57 I mean I can curl my way around GitHub's API easily but I don't recommend it 00:58:05 httpie makes it a little better 00:58:07 Some of their resources are huge (especially the collections) 00:58:12 elmiko: +1 00:58:13 my feeling is that it was about combinations of URI, headers and bodies… the intent is 'be simple and smart' 00:58:51 i think the idea of simplification is nice, but extending to json bodies sounds difficult 00:59:05 but it became a time sink…I'm ready to just let it go 00:59:27 I would agree with not including tenant ids in URIs whenever possible 00:59:30 Yeah I like the *intent* I just don't know how practical it really is 00:59:44 but I don't think there is much more that can be done 01:00:20 i don't like tenant ids in the URI either, taking that out will be a big change for sahara 01:00:43 it shouldn't be a problem if we had HATEAOS, but.... 01:01:06 that's a whole other kettle of fish... 01:01:10 yeah 01:01:16 and we're over time 01:01:24 #endmeeting