thoughts on how to perform actions on resources

[neonstalwart]

from @joe-mojo #16 (comment)

other role (no update) like sending a message to a resource (handler) or annotating en existing resource.

this raises a point i've been meaning to bring up... using URLs for actions (like /runs/{run_id}/actions/stop) is something that doesn't seem like the most correct thing to do. would it be more appropriate to recommend using something like JSON-RPC and POST /runs/{run_id} where the JSON-RPC request indicates the action to be performed?

[joe-mojo]

This a common mistake. Because of SOAP, people think it is always bad to use POST on a handler (rpc style). But it is what you do when creating an entity with POST. You ask a collection (or handler) to create a resource with the provided args.

It is OK to POST to a handler as long as you are sure it is impossible to use another verb. That's why RFC says you should use PUT/PATCH to create and update resource, but you can use POST as replacement anywhere you cannot use PUT nor PATCH, and anywhere the POST semantic is not create/update/delete.

I hate SOAP, mostly because it uses POST as a layer for everything. But when you do "righteous" HTTP, you must sometime use a resource nearly as an RPC endpoint. Saying it is a collection and not a handler us only playing with words.

Only practice makes difference between a bloated API with abusive POSTs and a good API with moderate use of POST; trying to forbid POST-to-handler strictly does not make senses.

[geemus]

I can see your point about using JSON-RPC or similar. I felt that /actions/... was more generally accessible. At least in part because it follows a very similar pattern to other stuff in the API, so it would hopefully still feel somewhat familiar. Similar to notes from @joe-mojo, I think we are also within the semantics of HTTP stuff to do it this way (though there are other ways that are legitimate as well).

[ilovenwd]

@geemus
what about collection actions?
/users/actions/xxx
what if a user's name is actions?

should we use the singular form?
/user/actions/xxx

[geemus]

@ilovenwd good questions. I haven't seen many instances of collection actions, do you have an example? I think it might be easier to discuss/work through a specific case than talk in general.

I think for the user case there it would be ok, albeit look kind of weird. I think the final url for a user with name actions would actually be /user/actions/actions/xxx. So it avoids ambiguity of name by keeping it in a different component/section of the slash separated list (so to speak). Of course you can ensure even more clarity by just using uuids everywhere, but that has it's own downsides (in terms of usability and just not being very fun to look at).

[geemus]

I've added a proposed way to work this in #89