16:00:47 <sigmavirus24> #startmeeting api wg
16:00:48 <openstack> Meeting started Thu Feb 12 16:00:47 2015 UTC and is due to finish in 60 minutes.  The chair is sigmavirus24. Information about MeetBot at http://wiki.debian.org/MeetBot.
16:00:49 <dtroyer> You are in the right place
16:00:50 <openstack> Useful Commands: #action #agreed #help #info #idea #link #topic #startvote.
16:00:54 <openstack> The meeting name has been set to 'api_wg'
16:01:10 <rosmaita> o/
16:01:18 <sigmavirus24> Hey everyone
16:01:50 <sigmavirus24> Seems etoews can't make it today so I volunteered to take over the hard hard work of chairing today ;)
16:01:59 <elmiko> yo/
16:02:01 <sigmavirus24> #topic agenda
16:02:03 <kaufer> hey all
16:02:08 <cdent> o/
16:02:30 <ryansb> hi
16:02:33 <sigmavirus24> #link https://wiki.openstack.org/wiki/Meetings/API-WG#Agenda
16:02:41 <rosmaita> did we have an etherpad with the various mission statements?
16:02:48 <elmiko> yes
16:02:53 <sigmavirus24> #topic mission statement
16:02:57 <elmiko> i don't think it was updated from last time though
16:02:59 * sigmavirus24 was going to find that :)
16:03:07 <sigmavirus24> unless someone else has it
16:03:13 <edleafe> o/
16:03:20 <elmiko> #link https://etherpad.openstack.org/p/api-wg-mission-statement
16:03:28 <clu_> hi
16:03:42 <sigmavirus24> #info mailing list thread http://lists.openstack.org/pipermail/openstack-dev/2015-February/055763.html
16:03:48 <ryansb> https://etherpad.openstack.org/p/api-wg-mission-statement
16:03:49 <sigmavirus24> Thanks elmiko
16:03:54 <ryansb> oop, too slow
16:03:57 <sigmavirus24> and ryansb :)
16:03:57 <elmiko> =)
16:04:11 <rosmaita> so my impression of the ML discussion is that stefano's is the favorite?
16:04:24 <sigmavirus24> Or something along those lines, yes
16:05:03 <sigmavirus24> (I think etoews had a few changes he wanted to make to it)
16:05:07 <ryansb> In essence, yes. I (only just posted) that I like how "API user" sounds, but even without that tweak +1 to stefano's
16:05:22 <sigmavirus24> #link http://lists.openstack.org/pipermail/openstack-dev/2015-February/056441.html
16:05:24 <elmiko> yea, stefano's is nice
16:05:27 <cdent> I prefer user to consumer as well, despite the weird connotations of both.
16:05:48 <edleafe> +1 to stefano's, even with the excessively long last sentence. :)
16:05:51 <sigmavirus24> cdent: yeah, why can't we just make up words to avoid overriding syntax in OpenStack?
16:06:29 <cdent> API flimflam with the frobnitz
16:06:41 <elmiko> lol
16:06:46 <sigmavirus24> cdent: +A
16:06:46 <ryansb> aaaand openstack-ese was born
16:07:16 <sigmavirus24> We want to discuss this further or should we move on? (I'm not really sure what etoews had wanted to say about this)
16:07:36 <cdent> move on
16:07:42 <sigmavirus24> #action etoews to wrap up conversation on the mailing list and disseminate our mission statement
16:07:46 <dtroyer> I think stefano's paragraph is a nice explanation/expansion, I still strongly prefer short and concise.  but will not hold things up, we spend too much time on this already
16:07:49 <sigmavirus24> #topic Glance and functional API
16:08:02 <sigmavirus24> rosmaita: want to take this one?
16:08:07 <elmiko> dtroyer: i thought the idea was to have a long version, and a short tweetable version?
16:08:08 <rosmaita> sure
16:08:22 <sigmavirus24> #link https://etherpad.openstack.org/p/glance-adding-functional-operations-to-api
16:08:25 <dtroyer> elmiko: tha's cool too
16:08:28 <sigmavirus24> #link https://review.openstack.org/#/c/135122
16:08:53 <rosmaita> not much to say, overall issue is "is there a place in openstack API for functional calls, and if so what should they look like?"
16:09:17 <rosmaita> the idea is that the current RESTful paradigm is extremely document-centric
16:10:03 <rosmaita> and not everything fits naturally into that paradigm
16:10:04 <rosmaita> but
16:10:19 <rosmaita> stuff can be forced into the paradigm if that's what's really wanted
16:10:38 <rosmaita> so the proposal is to introduce
16:11:01 <rosmaita> POST /v2/images/{image_uuid}/action/deactivate
16:11:09 <rosmaita> even though there's no "action"resource
16:11:31 <rosmaita> (and similar POST to reactivate)
16:11:44 <elmiko> does there need to be an "action" in the uri?
16:11:49 <ryansb> I like the idea of tasks as a resource foo/{}/action/frobozzle is ok without an action resource IMO since it acts as a namespace
16:12:23 <sigmavirus24> I think it's also important to note (since I've been involved in this discussion a lot) that the contention is that Glance may do more than just change a status field on the image so this is meant to hide implementation details ideally (taken for granted that the spec in question does nothing other than change the status field iirc)
16:12:54 <sigmavirus24> Also jaypipes had feedback on this coming from Nova but I'm not sure they're around
16:13:02 <rosmaita> sigmavirus24: that's basically correct
16:13:08 <cdent> what about POST /v2/images/{image_uuid}?deactivate or /v2/images{image_uuid};deactivate ? Your resources is still the image, you're just changing its state
16:13:43 <rosmaita> cdent: well, the key thing is that you are not changing the state, the state machine is under complete control of glance
16:13:57 <rosmaita> we don't want anyone to have the impression that it's ok to monkey with state
16:14:11 <rosmaita> both users and future devs
16:14:23 <ryansb> that's why tasks as a resource ae (IMO) better since you are manipulating a *request* not the resource state
16:14:46 <rosmaita> yeah, except we already have tasks as actual entities
16:14:56 <rosmaita> this seems a different kind of thing
16:15:02 <ryansb> hrm.
16:15:04 <rosmaita> we're requesting a function
16:15:09 <cdent> how is active or not active not part of the image's state? From the spec being "on hold" sounds exactly like state
16:15:28 <elmiko> cdent: i would think for a controller-ish action wouldn't it be better to have /v2/images/{id}/deactivate , or is that some sort of badness?
16:15:50 <rosmaita> elmiko: the actions part was in there jsut to group these things together
16:16:00 <rosmaita> don't necessarily have to have it
16:16:08 <rosmaita> but could keep things neat for later
16:16:08 <edleafe> elmiko: that looks like 'deactivate' is a resource
16:16:09 <elmiko> rosmaita: right, except that like you said there is no "action" resource
16:16:09 <ryansb> +1 on grouping
16:16:29 <rosmaita> elmiko: correct, no action resource, it's a function
16:16:31 <cdent> elmiko I prefer to put the resource and nothing else in the path part of the URI to preserve the sense to which it is an identifier
16:16:33 <elmiko> edleafe: i thought these type of endpoints were ok for exposing controller type actions?
16:16:48 <elmiko> cdent: got it
16:17:05 <rosmaita> we could replace "action" with "function" ... would that be more clear?
16:17:09 <edleafe> cdent: I like your idea, but with this tweak: POST /v2/images/{image_uuid}?action=deactivate
16:17:14 <rosmaita> "action" is overloaded in openstack
16:17:21 <cdent> yeah, that's fine edleafe
16:17:34 <cdent> every word is overload in openstack! :)
16:18:02 <elmiko> "action" seems fine to me, i was more responding to the idea that /action wasn't a resource
16:18:10 <ryansb> cdent: not the word "overloaded"...yet
16:18:15 <dtroyer> does moving the action=<foo> to the query string change the rationale for using POST over PUT?
16:18:16 <edleafe> rosmaita: replace 'action' with 'task' or 'job' or 'function' or ...
16:18:33 <rosmaita> well, can't do 'task', it's taken!
16:18:42 <edleafe> dtroyer: good point
16:18:44 <cdent> dtroyer: it would need to be POST, for PUT you're supposed to PUT the whole resoruce again
16:18:58 <sigmavirus24> cdent: except the POST body here is empty
16:19:02 <sigmavirus24> (according to the spec)
16:19:04 * cdent struggles to type well
16:19:10 <cdent> sigmavirus24: yeah, that's okay
16:19:23 <cdent> (IMO)
16:19:35 <rosmaita> i'm with cdent on not using PUT
16:19:52 <salv-orlando> fwiw I too think POST is the appropriate verb here.
16:20:01 <cdent> PUT has very specific semantics whereas POST is just sort of "aw hell, nothing else fits"
16:20:24 <cdent> so in this case we are saying "I want to deactivate this image"
16:20:39 <cdent> that's a server-side state changing operation so thus is POST
16:20:51 <cdent> whether it has a body or not is not relevant
16:20:58 <dtroyer> ok…was just reading the rationale, the POST==catch-all bit helps me…move along…
16:21:29 <salv-orlando> In my understanding POST semantics pretty much means "I instruct you, server, to do this for me"
16:21:34 <rosmaita> ok, let's stick with POST, then?  everyone OK with that?
16:21:39 <cdent> +1
16:21:41 <sigmavirus24> Seems that way
16:21:54 <sigmavirus24> Also we're nearing on 15 minutes on this ;)
16:21:59 <rosmaita> next thing would be dtroyer's suggestion of query string instead of resource look
16:22:08 <rosmaita> (really want to get this settled)
16:22:43 <cdent> I'm +1 on query string
16:22:44 <rosmaita> we discussed & rejected in atlanta, but i can't remember whhy
16:23:04 <sigmavirus24> cdent: why?
16:23:34 <rosmaita> may have rejected query string because it confuses things for rate limiting and the controller, maybe?
16:23:34 <cdent> because it keeps the image being the resource, not some other thing that isn't actually a resource
16:23:48 <edleafe> cd +1
16:23:54 <edleafe> cdent: +1
16:24:03 * edleafe curses his fat fingers
16:24:19 <dtroyer> it also fits with the notion of instructing the server to do something…we do the same with sort, which changes the servers behaviour
16:26:11 * sigmavirus24 wasn't against it, just trying to help everyone understand the reasoning for being +1 on it ;)
16:26:35 <elmiko> i'm a little confused about the notion of having endpoints that are not resources. my main expose is the o'reilly book on rest design, but they specify that endpoints for actions are ok under some circumstances, is this generally bad rest practice?
16:26:58 <elmiko> *exposure
16:27:01 <rosmaita> elmiko: depends on who you ask!
16:27:07 <elmiko> exactly... lol
16:27:13 <cdent> elmiko in my experience its okay to have a resource which is an action: for example /differ which takes to args
16:27:14 <sigmavirus24> elmiko: so much of this is subjective IMO
16:27:16 <cdent> s/to/two
16:27:20 <cdent> as query parameters
16:27:48 <cdent> but if you've already got a resource adding an action on it as a yet another resource is a bit funky
16:27:54 <sigmavirus24> Somethings are more widely agreed upon than others though so you have overlapping opinions
16:28:09 <elmiko> cdent: ok, that clears up the difference
16:28:46 <rosmaita> i really don't like the query parameter approach, but i can't think of a good argument
16:28:57 <elmiko> i get it about the opinions, i was just missing the issue about adding on to a resource
16:29:35 <sigmavirus24> #startvote Is the API WG's recommendation to use POST with a query parameter, e.g., /images/{id}?action=deactivate, instead of a functional API, e.g., /images/{id}/action/deactivate?
16:29:36 <openstack> Begin voting on: Is the API WG's recommendation to use POST with a query parameter, e.g., /images/{id}?action=deactivate, instead of a functional API, e.g., /images/{id}/action/deactivate? Valid vote options are Yes, No.
16:29:37 <openstack> Vote using '#vote OPTION'. Only your last vote counts.
16:29:38 <cdent> rosmaita: have you considerd a PATCH with a body of '{"active": false}'
16:29:47 <sigmavirus24> cdent: yes and that was shot down
16:29:59 <cdent> interesting
16:30:28 <ryansb> why was PATCH downvoted?
16:30:32 <ryansb> Seems like a fit to me
16:30:37 <rosmaita> cdent: doesn't really fit the PATCH semantics
16:30:52 <rosmaita> well, the key thing is that you can make it look like a PATCH, but it really isn't
16:31:18 <dtroyer> rosmaita: but does the api caller care?
16:31:30 <rosmaita> no, but we are thinking of developers here
16:31:39 <dtroyer> that's who I am talking about
16:31:44 <rosmaita> the problem is that people come and go on projects
16:31:49 <sigmavirus24> #endvote since we threw a monkey wrench into the discussion
16:31:50 <openstack> Voted on "Is the API WG's recommendation to use POST with a query parameter, e.g., /images/{id}?action=deactivate, instead of a functional API, e.g., /images/{id}/action/deactivate?" Results are
16:32:00 <cdent> sorry sigmavirus24
16:32:12 <sigmavirus24> No need to apologize cdent. i started it too early ;)
16:32:36 <sigmavirus24> rosmaita: not to sound like a jerk but, isn't that what specs are for? To document this for future developers on the project?
16:32:36 <rosmaita> dtroyer: i mean the glance developers ourselves
16:32:53 <dtroyer> I don't understand why that influences the api design?
16:33:17 <edleafe> PATCH is simply a partial PUT. It really doesn't fit what we're talking about.
16:33:47 <dtroyer> it seems to me to be exactly what we are talking about…an api caller things this is a simple state change, internally it is totally something else evidently
16:33:58 <cdent> edleafe: how so? a patch is what you want to do when you want to change part of a resource rather than replace it
16:34:18 <cdent> we want to change the resource from active to not active, yes?
16:34:23 <dtroyer> I suppose my PUT question earlier should have been PATCH…
16:34:24 <edleafe> cdent: exactly. PUT is when you want to replace it
16:35:24 <edleafe> cdent: it's more than just changing one thing on a resource, no?
16:35:43 * edleafe isn't too familiar with glance internals
16:35:43 <miguelgrinberg> sorry to arrive late to the party, but is the discussion now centered on POST vs. PUT vs. PATCH alone? Are we giving up on RESTfulness?
16:35:45 <rosmaita> dtroyer: not sure this makes sense, but there are some things glance should be in complete charge of.  i am afraid that if we make it look like you can change image state, someone will put in a change making that happen
16:36:25 <edleafe> miguelgrinberg: quite the opposite
16:36:29 <dtroyer> but that is exactly what you are doing…an admin who deactivates an image is overriding glance
16:36:38 <sigmavirus24> rosmaita: so the thing is that cores will ideally be familiar with the idea that this shouldn't be allowed and block that particular patch
16:36:40 <miguelgrinberg> edleafe: good, reading now
16:36:55 <rosmaita> sigmavirus24: one would think so, but i've seen some pretty weird stuff get in
16:37:36 <rosmaita> dtroyer: you're not really overriding glance, you are asking glance to make something happen if possible
16:37:37 <cdent> rosmaita: how does the structure of the url have any bearing on whether or not people will try to use the functionality?
16:37:53 <rosmaita> cdent: i mean people maintaining the API
16:38:29 <dtroyer> rosmaita: I simply do not see how deactivating an image is not a state change,
16:38:53 <cdent> presumably whatever code path that handles deactivation will be guarded by admin checks that are suitably visible that some subsequent dev will notice?
16:38:57 <dtroyer> it is called that on line 28
16:39:29 <cdent> if glance doesn't want to do it, it responds with a 40x (probalby 3)
16:39:41 <cdent> done
16:39:58 <salv-orlando> dtroyer: it is a state change indeed. But such change is triggered by executed action, rather than by processing the request sent to the server.
16:40:01 <salv-orlando> Is this correct?
16:40:12 <rosmaita> yeah, i guess it's just an intuition i have.  it just seems different to me
16:40:22 <rosmaita> salv-orlando: yes
16:40:30 <rosmaita> that's a nice way to put it
16:40:57 * jaypipes really despises the /resources/{id}/actions stuff.
16:41:00 <dtroyer> salv-orlando: right, I don't see much difference though, in the semantic game of not saying state change in the api
16:41:32 <elmiko> jaypipes: what's your feeling on /resources/{id}?actions ?
16:41:43 <cdent> I think we need vote or punt or we'll be on this the entire meeting.
16:41:53 <rosmaita> cdent: +1
16:42:11 <sigmavirus24> cdent: agreed but wanted rosmaita to not feel like we were trying to delay this more
16:42:11 <jaypipes> elmiko: I don't like that either :)
16:42:19 <elmiko> jaypipes: ha!
16:42:31 <elmiko> jaypipes: how to expose controller type actions then?
16:42:31 <dtroyer> I'd suggest a deferment and clarify the points at question
16:42:39 <jaypipes> elmiko: I prefer POST /resources/{id}/tasks with a payload describing the task.
16:42:40 <sigmavirus24> dtroyer: seems fair
16:42:40 <elmiko> dtroyer++
16:42:51 <elmiko> jaypipes: got it
16:42:59 <miguelgrinberg> jaypipes: sorry, but that's still an action, don't like that either
16:43:00 <cdent> jaypipes-- :)
16:43:15 <sigmavirus24> So we should definitely move this to the Mailing LIst
16:43:23 <elmiko> sigmavirus24++
16:43:28 <sigmavirus24> Can we all be more mindful about responding this time?
16:43:37 <sigmavirus24> I know rosmaita brought it up there before but got almost no responses
16:43:47 <miguelgrinberg> either define a resource that represents that action happening or not and edit that resource, or add state to the main resource to indicate if that action needs to occur (i.e. a change of state in the resource)
16:43:59 <sigmavirus24> Moving on
16:44:00 <sigmavirus24> #topic versioning
16:44:01 <ryansb> yeah, though can folks make sure to use the [API] tag? I missed the mission statement thread for a while because it lacked it
16:44:13 <sigmavirus24> #link https://review.openstack.org/#/c/148037/
16:44:25 <sigmavirus24> #link http://specs.openstack.org/openstack/nova-specs/specs/kilo/approved/api-microversions.html
16:44:47 <sigmavirus24> Did someone other than etoews add this?
16:45:04 <jaypipes> miguelgrinberg: a task is an object. an action is an action.
16:45:38 <rosmaita> jaypipes: +1
16:45:52 <miguelgrinberg> jaypipes: we can agree to disagree
16:45:54 <sigmavirus24> #action sigmavirus24 to carry this topic forward to next week
16:45:56 <jaypipes> :) sure
16:46:10 <sigmavirus24> #topic previous meeting action items
16:46:18 <sigmavirus24> #link http://eavesdrop.openstack.org/meetings/api_wg/2015/api_wg.2015-02-05-00.00.html
16:46:46 <sigmavirus24> Seems all of the previous action items were taken care of.
16:46:47 <cdent> success!
16:47:06 <sigmavirus24> #topic guidelines
16:47:11 <sigmavirus24> #link https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z
16:47:48 <sigmavirus24> I think we need jaypipes or someone else to abandon https://review.openstack.org/#/c/132248/
16:47:52 <sigmavirus24> #link https://review.openstack.org/#/c/132248/
16:48:12 <sigmavirus24> We should also try to get more cross-project attention on https://review.openstack.org/#/c/147684/
16:48:17 <jaypipes> sigmavirus24: done.
16:48:22 <sigmavirus24> Thanks jaypipes
16:48:29 <sigmavirus24> kaufer: are you around?
16:48:33 <kaufer> yep
16:48:43 <sigmavirus24> Mind if I assign you to grab more eyes on that?
16:48:50 <kaufer> I'd like to get jaypipes thoughts on https://review.openstack.org/#/c/147684/
16:49:49 <sigmavirus24> #action kaufer to get some more input from other project members on https://review.openstack.org/#/c/147684/
16:49:54 <miguelgrinberg> kaufer: I would just add that this is necessary only when getting the count can be seen as affecting performance. If not, then APIs are free to always return the count.
16:49:58 <jaypipes> kaufer: reviewed.
16:50:10 <sigmavirus24> heh
16:50:45 <sigmavirus24> Anything else from https://review.openstack.org/#/q/status:open+project:openstack/api-wg,n,z we want to discuss?
16:51:12 <miguelgrinberg> so there is a discussion on tags in the Heat channel, I'm thinking in expanding the metadata guideline to include also tags
16:51:29 <miguelgrinberg> or would you guys prefer a separate doc?
16:51:40 <sigmavirus24> miguelgrinberg: perhaps it'd be better to make that dependent since metadata guidelines are already seemingly controversial
16:51:42 <sigmavirus24> #info metadata guideline https://review.openstack.org/#/c/141229/
16:51:52 <jaypipes> miguelgrinberg: would be great to include the server tagging API (from Nova, based heavily on Glance's) in that discussion
16:51:58 <cdent> miguelgrinberg: I'd choose separate
16:52:08 <miguelgrinberg> jaypipes: that's what we were looking at for heat, yes
16:52:15 <jaypipes> rock on.
16:52:31 <miguelgrinberg> okay, I'll do a separate doc on tagging then
16:52:40 <sigmavirus24> Cool
16:53:02 <sigmavirus24> #action miguelgrinberg to make a guideline for tagging
16:53:24 <sigmavirus24> Other guidelines we want to discuss or should we move on to APIImpact?
16:53:32 <ryansb> miguelgrinberg: if you'd like a hand I'm happy to help w/ that
16:53:53 <miguelgrinberg> ryansb: sure, I'll find you when I have a first draft
16:54:03 <ryansb> sgtm
16:54:47 <sigmavirus24> No one seems to object to moving on, so
16:54:47 <sigmavirus24> #topic APIImpact
16:54:58 <sigmavirus24> #link https://review.openstack.org/#/q/status:open+AND+(message:ApiImpact+OR+message:APIImpact),n,z
16:55:16 <sigmavirus24> Anything anyone wants to point out here?
16:57:10 <cdent> guess not?
16:59:03 <ryansb> no, looks like most of those are being well-handled by the project team
16:59:09 <ryansb> *teams
16:59:29 <miguelgrinberg> the heat tags spec is missing, just added a note for the author to add the flag
16:59:38 <ryansb> good catch
17:02:07 <sigmavirus24> And we're over time
17:02:08 <cdent> times up?
17:02:10 <cdent> jinz
17:02:11 <sigmavirus24> Sorry about that
17:02:12 <cdent> x
17:02:12 <sigmavirus24> Got distracted
17:02:13 <sigmavirus24> #endmeeting