How to design REST API for non-CRUD "commands" like activate and deactivate of a resource?

Question

Before I decided to ask this question I have searched quite a long for the answer but I haven't found any satisfactory. (e.g. Examples of the best SOAP/REST/RPC web APIs? And why do you like them? And what's wrong with them?)

And the problem is actually quite simple. I have an object/resource named Account. My REST API supports all CRUDs with GET, POST, PUT and DELETE already with proper error handling, status codes etc.

Additionally however I want to expose an API ("command") to activate and deactivate selected Account resource. Even if the "isActive" is a property of the Account I don't want to use just the Update from my CRUD of the whole Account.

I know it is easy to violate REST principles and make RPC style design with such design like this:

PUT /api/account/:accountId/activate

PUT /api/account/:accountId/deactivate

So what is the best solution for this use case?

My current idea is to use PUT and DELETE verbs like this (to treat it as a sub-resource) as proposed here http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api#restful:

PUT /api/account/:accountId/isActive // for activate

DELETE /api/account/:accountId/isActive // for deactivate

What are your solutions?

Answer 1

How about coming up with a noun for the feature you want to modify - 'status' in this instance. This would then become a sub resource of the parent entity. So for your case I would model the URI as follows:

/api/accounts/{accountId}/status 

If the 'update' semantics are idempotent then PUT would be most appropriate, else that would need to be a POST (e.g if nonces are involved and are invalidated by the service). The actual payload would include a descriptor for the new state.

Note, I pluralized 'accounts' since you can have multiple of those, but status is singular since your account can have only one state.

Answer 2

PATCH is the most appropriate method in this case. Please find more at RESTful URL for "Activate"