00:00:21 <etoews> #startmeeting api wg
00:00:22 <openstack> Meeting started Thu Dec 11 00:00:21 2014 UTC and is due to finish in 60 minutes.  The chair is etoews. Information about MeetBot at http://wiki.debian.org/MeetBot.
00:00:23 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
00:00:25 <openstack> The meeting name has been set to 'api_wg'
00:00:36 <etoews> anyone else here for the api wg meeting?
00:00:44 <rosmaita> o/
00:00:59 <etoews> hello sir
00:01:01 <ryansb> o/
00:01:08 <eliqiao> o/
00:01:24 <etoews> good day/evening to all!
00:01:38 <elmiko> o/
00:01:43 <etoews> #topic agenda
00:01:49 <etoews> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
00:02:30 <etoews> as you can probably tell i structured the wiki meeting page to be easy to copy/paste meetbot commands from
00:02:41 <rosmaita> good idea
00:03:05 <etoews> i'm thinking i'll put a "placeholder" in for *new* specific topics at the start
00:03:27 <etoews> if there's something beyond our regular review and such, we should tackle it first.
00:03:54 <etoews> so anyone is always welcome to update the agenda to put a specific topic
00:04:03 <elmiko> nice
00:04:04 <etoews> #topic previous meeting action items
00:04:19 <etoews> #link http://eavesdrop.openstack.org/meetings/api_wg/2014/api_wg.2014-12-04-16.01.html
00:05:03 <etoews> cyeoh merged the Process for merging guideline changesets https://review.openstack.org/#/c/131358/ !
00:05:21 <elmiko> yea, that was nice. seemed like we had a good consensus.
00:05:25 <etoews> that really means we're off and running now
00:05:29 <stevelle> o/
00:06:25 <etoews> my guideline met that criteria and was merged today by jaypipes https://review.openstack.org/#/c/133087/
00:06:53 <elmiko> very cool
00:06:57 <etoews> when i say "my" i mean ours. that one started at the summit during a design session and a bunch of us worked on it.
00:07:51 <etoews> i emailed the magnetodb team and gave them an intro to the api wg on the ml
00:07:59 <etoews> it was pretty well received.
00:08:24 <elmiko> good to hear
00:08:28 <ryansb> yeah, saw that on the ML
00:08:35 <etoews> isviridov is now our liaison https://wiki.openstack.org/wiki/CrossProjectLiaisons#API_Working_Group
00:09:17 <etoews> ycombinator had an action item
00:09:56 <etoews> looks like he's not online atm.
00:10:55 <etoews> there's another action item for all of us but it belongs under apiimpact anyway
00:11:08 <elmiko> lol, nice
00:11:16 <etoews> #topic APIImpact
00:11:29 <etoews> #link https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z
00:11:46 <etoews> the one we were requested to review was https://review.openstack.org/#/c/136760/
00:11:49 <etoews> #link https://review.openstack.org/#/c/136760/
00:12:11 <etoews> i confess i didn't get to it amongst everything else... :(
00:12:15 <miguelgrinberg> hello, late again :-)
00:12:35 <etoews> did anyone have a look at it?
00:13:02 <elmiko> not me, but looks like that review has generated a large amount of comments.
00:13:07 <rosmaita> sorry, no, i am way behind
00:14:08 <etoews> no worries.
00:14:33 <etoews> elmiko: good point. it's got a fair amount of eyes on it already.
00:15:07 <etoews> anything else from https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z that someone would like to call out?
00:15:23 <miguelgrinberg> I reviewed https://review.openstack.org/#/c/136253/
00:15:38 <miguelgrinberg> it's an interesting one, it has a definition on how to add/remove from a list of things
00:16:08 <miguelgrinberg> I suggested an approach that they did not like, because it is different to what they are doing now in other parts of the API
00:16:24 <miguelgrinberg> they use a PUT with a partial resource representation
00:17:34 <miguelgrinberg> I think we should decide what is the approach to recommend going forward for dealing with lists of things
00:17:55 <etoews> is it a membership type of relationship or just a plain list of things?
00:18:18 <miguelgrinberg> it's not a list of resources, these are metadata items
00:18:27 <etoews> okay
00:18:30 <miguelgrinberg> associated with a volume in this case
00:18:58 <miguelgrinberg> they want to send PUT with key:value for new items, and key with empty value to delete
00:19:15 <etoews> oh
00:19:18 <elmiko> wouldn't that be normal for updating a resource?
00:19:19 <miguelgrinberg> a more correct approach IMHO would be to send the complete list in the PUT request
00:19:31 <miguelgrinberg> if you want to delete just not send what you want out
00:19:48 <elmiko> miguelgrinberg: that seems like a more complete solution
00:20:04 <etoews> that's puts a bigger burden on the client
00:20:08 <elmiko> does it burden the client to carry too much info though?
00:20:08 <miguelgrinberg> it ensure you know what the collection is, if not it is kind of unpredictable
00:20:28 <miguelgrinberg> I guess, you need to issue a GET to have the list
00:20:43 <miguelgrinberg> but it is likely the client already has that
00:21:00 <etoews> i wouldn't make that assumption
00:21:10 <etoews> take a cli for example
00:21:27 <etoews> it's not storing any info anywhere
00:21:30 <ryansb> also there's the "what if it changed"
00:21:35 <etoews> starting from 0 every time
00:21:53 <elmiko> good points
00:21:54 <miguelgrinberg> yeah, but adding to a list of things without knowing what's there in the first place it is not safe
00:21:58 <etoews> ryansb: yep. a kind of race condition scenario
00:22:03 <ryansb> if the list changed between your GET and PUT that would be bad
00:22:04 <miguelgrinberg> it forces the server to deal with duplicates
00:22:38 <miguelgrinberg> race conditions can happen in many other circumstances too
00:23:17 <ycombinator_> is adding/setting idempotent in this case (as its metadata)?
00:23:25 <elmiko> what about using some of the info, a partial record, to update with? ie just the essential plus your update
00:23:37 <etoews> i think sending the whole list to delete 1 thing would be particularly susceptible to that
00:24:05 <miguelgrinberg> so going by the book, you would do that with a PATCH request, PUT should get the whole thing
00:25:18 <elmiko> ycombinator_: seems like it _should_ be... not sure how it's actually used in their code.
00:26:10 <etoews> what about treating metadata as its own resource and just issuing a DELETE?
00:26:30 <etoews> whether or not it is its own resource on the backend.
00:26:39 <miguelgrinberg> etoews: that works, but you need to treat each metadata item as an individual resource, it can be overkill
00:26:55 <elmiko> interesting idea though
00:27:09 <stevelle> a PATCH is just so much cleaner and easier to reason about
00:27:10 <miguelgrinberg> how it is stored in the server does not matter, but the API will have to expose each item as an individual resource with its own URI
00:27:16 <etoews> overkill in that there could be a lot?
00:27:32 <miguelgrinberg> yeah, a lot of resources, and not much content in each
00:27:37 <miguelgrinberg> just a value
00:27:44 <dtroyer> etoews: yes…a lot of round-trips
00:28:12 <elmiko> is there a compelling reason not to recommend the PATCH operation?
00:29:42 <miguelgrinberg> so I'm not completely happy with how they delete stuff, even with PATCH that would have to stay the same
00:29:51 <miguelgrinberg> they set a key with an empty value
00:30:09 <ycombinator_> (sorry, I'm having network issues)
00:30:41 <miguelgrinberg> even for a PATCH, that does not seem RESTful to me
00:31:19 <dtroyer> I'm on the fence about that one…doing the key-only for delete simplified a bunch in OSC
00:31:20 <elmiko> miguelgrinberg: are you saying the even with a PATCH the whole list should be sent?
00:31:47 <elmiko> *that even
00:31:54 <miguelgrinberg> elmiko: I'm not sure what I'm saying, just that deleting something with a PATCH request seems odd
00:32:12 <elmiko> gotcha
00:32:22 <miguelgrinberg> what would be the possible responses to that? 200 if it worked, and what if the item does not exist?
00:32:24 <miguelgrinberg> 400?
00:32:47 <elmiko> good questions
00:32:59 <miguelgrinberg> you can't send a 404, since it's not a resource you are deleting
00:33:01 <ycombinator_> is deleting an item that does not exist an error?
00:33:12 <miguelgrinberg> ycombinator_: another good question, it depends on that case I guess
00:33:38 <etoews> for reference, nova treats metadata as a resource http://developer.openstack.org/api-ref-compute-v2.html#compute_server_metadata
00:34:08 <ycombinator_> I like the PATCH approach because its not chatty but my only concern is the representation of the key's value for deletion - what if null/0 are valid values for a key?
00:34:11 <dtroyer> also, in this case at least, the metadata is a single field (a dict) at the volume record level.
00:34:43 <miguelgrinberg> well, we have a precedent, this looks much nicer than what they intend to do
00:35:02 <elmiko> having the metadata endpoint seems really nice
00:35:16 <miguelgrinberg> they even implemented PUT for the whole metadata set
00:35:20 <etoews> cinder snapshots treat it as a resource http://developer.openstack.org/api-ref-blockstorage-v2.html#snapshots-v2
00:35:21 <miguelgrinberg> nice
00:36:09 <etoews> heh. i forgot that this is a cinder spec!
00:36:35 <etoews> they didn't look at their own api to ensure they were at least consistent with that?
00:36:50 <miguelgrinberg> do we need a spec on working with metadata items?
00:37:00 <miguelgrinberg> something we can refer to?
00:37:14 <etoews> miguelgrinberg: do you mean a guideline?
00:37:21 <miguelgrinberg> sorry, yes, that's what I meant
00:37:31 <etoews> yes. i think you're right. we do.
00:37:32 <elmiko> +1
00:37:35 <etoews> desparately
00:37:54 <ycombinator_> is metadata a special case or do we need a guideline for updating some items in lists?
00:38:13 <etoews> i think metadata is something of a special case
00:38:23 <etoews> just because it's used in so many places.
00:38:25 <miguelgrinberg> yeah, metadata is special, it's key-value lists
00:38:40 <miguelgrinberg> for other resources you can use regular REST stuff
00:39:07 <ycombinator_> I guess that's what I'm getting at - what is the downside of applying regular REST to metadata as well?
00:39:14 <etoews> miguelgrinberg: did you want to take an action item to comment about it on that review?
00:39:19 <ycombinator_> so the sub-resource for each metadata key idea that everett proposed earlier
00:39:23 <miguelgrinberg> yes, I will do that
00:40:03 <miguelgrinberg> ycombinator_: I think we are saying that we need to apply REST to metadata items, but we also need ways to get or replace this data in one chunk, for practical purposes
00:40:19 <miguelgrinberg> the nova example llinked above is a good one in my opinion
00:40:33 <etoews> #action miguelgrinberg to comment on https://review.openstack.org/#/c/136253/ to point out that metadata works better as its own resource, just like for cinder snapshots http://developer.openstack.org/api-ref-blockstorage-v2.html#snapshots-v2
00:40:54 <ycombinator_> okay, so metadata is special because unlike other lists of resources, it needs to be updated en-masse more frequently - got it!
00:41:01 <ycombinator_> we should probably clarify that in the guideline
00:41:36 <etoews> is there an action item here to create a guideline for metadata?
00:41:51 <elmiko> sounds like it
00:41:52 <etoews> if so, who's got it?
00:41:52 <miguelgrinberg> I think it would be useful
00:42:00 <ycombinator_> I'm happy to take a crack at it
00:42:29 <ycombinator_> unless it makes sense to keep both actions with miguelgrinberg since they are related
00:42:48 <miguelgrinberg> I'm fine either way, I can write an initial doc to review next week if you want
00:43:00 <ycombinator_> +1
00:43:36 <etoews> #action miguelgrinberg to write up an initial guideline to review for metadata to be consistent across openstack
00:43:44 <etoews> let's move on
00:43:53 <etoews> #topic guidelines
00:44:00 <etoews> #link https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
00:44:48 <etoews> i think we had an action item from before to review ycombinator_ guideline https://review.openstack.org/#/c/133660/
00:45:19 <ycombinator_> yes, I was supposed to put some stats in a comment
00:45:26 <ycombinator_> I have not had a chance to get to it :(
00:45:41 <etoews> my initial thought is that trying to cover both singular and collection resources in the same proposal was biting off too much
00:45:45 <ycombinator_> I'm also wondering if its better to split this guideline into two
00:45:47 <ycombinator_> ha
00:45:49 <etoews> heh
00:45:57 <ycombinator_> there's consensus on collections, I think
00:46:01 <ycombinator_> so I'd rather just start with that
00:46:05 <etoews> sounds good
00:46:23 <miguelgrinberg> +1, let's get collections done first
00:46:29 <ycombinator_> #action ycombinator to restrict scope of https://review.openstack.org/#/c/133660/ to collections only
00:46:58 <etoews> or close that one completely and start fresh?
00:47:24 <etoews> but then you lose easy access to the historical discussion on collections.
00:47:25 <ycombinator_> sure
00:47:29 <etoews> your call
00:47:29 <ycombinator_> yeah
00:48:08 <etoews> hmmm...considering you'd have to change the commit message a new one might be advisable. then link to the old one in the comments.
00:48:17 <ycombinator_> true - okay, I'll do that
00:48:20 <etoews> anyone else have advice on how to proceed here?
00:48:43 <elmiko> i dunno, seems a shame to lose the history
00:48:58 <ryansb> I'd go ahead and change the review
00:48:59 <dtroyer> what is the concern about changing the commit message?
00:49:07 <ryansb> (not make a new CR)
00:49:12 <ycombinator_> I can put in a comment saying I'm going to rework the patch, including changing the commit message
00:49:21 <ycombinator_> that way if someone read the comments, they'll know what happened
00:49:36 <ryansb> the change to the commit message will be part of the patch
00:49:40 <ycombinator_> right
00:49:46 <ryansb> so folks could see anyways
00:49:52 <etoews> sgtm
00:50:11 <etoews> 5 min to discuss anything else in https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
00:50:59 <elmiko> https://review.openstack.org/#/c/137490/ might need a few more eyes
00:51:00 <ryansb> or if folks don
00:51:16 <ryansb> *don't have other topics, we can probably adjourn early
00:51:23 <miguelgrinberg> when are we going to start merging these guidelines?
00:51:44 <etoews> that's what i was just looking at...
00:51:49 <etoews> https://review.openstack.org/#/c/130825/ looks mergable.
00:51:49 <rosmaita> ryansb: i have a topic for open discussion
00:52:09 <elmiko> i have an item for open disc. too
00:52:29 <etoews> to look up the merge permissions on any project, use a URL like this:
00:52:29 <etoews> https://review.openstack.org/#/admin/projects/openstack/api-wg,access
00:52:42 <etoews> you can click to see who belongs in the group with access control:
00:52:42 <etoews> https://review.openstack.org/#/admin/groups/468,members
00:52:56 <etoews> cyeoh and jaypipes can merge.
00:53:28 <etoews> i know cyeoh is still recovering. i'll ping jay to review the queue and merge what meets the criteria.
00:54:01 <etoews> #action etoews ping jay to review the queue https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z and merge what meets the criteria.
00:54:23 <etoews> #topic open topics
00:54:28 <etoews> shoot rosmaita
00:54:54 <rosmaita> anyone have a reaction to nova dropping xml in v2 ?
00:55:06 <rosmaita> didn't bother me when i thought there would be v3
00:55:16 <rosmaita> but it seems a bit weird
00:55:21 <etoews> i had a reaction to it a long time ago but then i got over it.
00:55:33 <rosmaita> i am late to the party
00:55:34 <miguelgrinberg> somebody somewhere is probably using it
00:55:40 <etoews> definitely
00:55:57 <rosmaita> guess that train has left the station
00:56:23 <etoews> i think so. i fought it for a bit but then folded like a house of cards. :(
00:56:26 <miguelgrinberg> it would be awesome if some day content types are abstracted in a framework that all APIs use
00:56:39 <elmiko> miguelgrinberg: +1
00:56:41 <miguelgrinberg> then it does not matter, all we see are Python dicts
00:56:42 <rosmaita> that would indeed be awesome
00:56:51 <rosmaita> ok, that's all i had
00:57:05 <elmiko> mine is mainly informational
00:57:12 <elmiko> at summit we talked briefly about swagger
00:57:25 <etoews> yes
00:57:30 <elmiko> i have a poc prototype up for sahara to generate the base required doc for swagger 2.0
00:57:35 <elmiko> https://github.com/elmiko/sahara-doc
00:57:54 <elmiko> very proto still, but i'm going to add more to it and create a WADL->Swagger generator as well
00:58:18 <elmiko> right now it just dumps the json output, but i want to build a server in too
00:58:24 <etoews> said wadl > swagger generator may already exist.
00:58:39 <etoews> let's make this a top level topic for next meeting!
00:58:44 <elmiko> yea, i think Max Lincoln had something going, i still need to get in touch with him.
00:58:52 <ycombinator_> https://pypi.python.org/pypi/wadl2swagger/0.0.2
00:58:58 <elmiko> oh awesome!
00:59:04 <elmiko> ycombinator_: thanks
00:59:19 <miguelgrinberg> it would be awesome to omit the syntax of reousrces in API docs, just saying
00:59:32 <miguelgrinberg> so that people are not encouraged to build URLs on the client side
00:59:47 <ycombinator_> +1
00:59:51 <elmiko> miguelgrinberg: not sure i follow, could you elaborate a little?
01:00:03 <miguelgrinberg> you do not need to show how URLs are formed
01:00:15 <miguelgrinberg> because we want clients to get URLs from links in other resources
01:00:22 <elmiko> ahh ok
01:00:24 <ycombinator_> miguelgrinberg: do you have an example?
01:00:27 <miguelgrinberg> the only URLs that should be public are the top-level ones
01:00:35 <elmiko> makes good sense
01:00:38 <etoews> gonna have to end the meeting now...
01:00:40 <miguelgrinberg> I need to dig for one, I promise to bring one next week
01:00:47 <ycombinator_> cool
01:00:52 <rosmaita> bye
01:00:57 <miguelgrinberg> bye guys
01:00:58 <ycombinator_> bye
01:01:01 <etoews> #endmeeting