What are the disadvantages custom actions in "REST" endpoints?

I have to admit, I've struggled for a long time to fully grasp the advantages and disadvantages of RESTful resource endpoints.

I've often heard that RESTful APIs should consider everything as a resource, and NOT to send messages, or commands.

For example, say I wanted to be able to activate or deactivate a resource like account. My strong inclination, against most of what I've read is to have endpoints that looks like:

PUT accounts/1/activate

PUT accounts/1/deactivate

I feel like I'm misunderstanding something important even after a long time making apps, because it seems the RESTful approach would be something like:

POST accounts/1/activation

DELETE accounts/1/activation

Or something similar. I've even had a colleague who preferred something like:

PUT accounts/1?activate=true

PUT accounts/1?deactivate=true

And inside the update action, there would just be a long if ... then chain looking for flags to figure out what to "do".

if params[:activate]
  # do some activation stuff

The latter approaches just don't seem advantageous to me, and I'd really like to understand what I'm missing.

The "command" approach has more advantages to my mind, because it makes it clear what the purpose of the endpoint is, separates behavior out on the server, and in many cases obviates the need for the client to know what attributes to pass in order to get the job done. I am however very open to hearing disadvantages to this and advantages of the latter approaches.

Could someone enlighten me please?

> I have to admit, I've struggled for a long time to fully grasp the advantages and disadvantages of RESTful resource endpoints.

Not your fault - the literature sucks.

> The latter approaches just don't seem advantageous to me, and I'd really like to understand what I'm missing.

My guess: what you are missing is that HTTP is an application protocol - it transfers and manipulates "documents" (resources) over a network. See Webber 2011.

Useful work is a side effect of manipulating resources.

For example:

PUT /accounts/1/activate

doesn't mean "activate account 1". What is means is "replace your representation of /accounts/1/activate with the included payload" - activating the account is the side effect.

Designing a resource model is thinking about what side effects we need, and which alternative offers us the best tradeoffs.

Since not everybody gives the same weights to the different trade offs available, you get a lot of different ideas about which resource model is the best fit.

One of the tradeoffs to consider in designing your resource model: how much information are you giving to the HTTP application itself?

We certainly could design a resource model where everything happens via

POST /

or everything happens via

PUT /{someUUID}

but neither of those approaches correctly identify safe requests, or help caches to understand whether to invalidate a previously stored response, or tell our operators reading the access logs anything useful about how the system is being used, they don't simplify our concerns with access control, and so on.

(I'll note in passing that while HTTP cares a lot about whether the resources in your model understand messages the same way everybody else on the internet understands them, what HTTP does not care about at all is how easy/difficult your resource model is to implement.)

We could design our resource model such that the activate account side effect is induced by editing the /accounts/1/activate document, OR we could instead activate that same side effect by editing the /accounts/1 document. Both choices are "fine", but they have different caching implications to consider.