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