how to expose complex actions in RESTApi using http verbs

Question

consider the following REST resource Account

{
  number:"number-000", 
  name: "name", 
  customer : {}, 
  type : {}, 
  status : "status", 
  balance : 0, 
  rating : 0.0
}

Now say we have the following CRUD operations:

• [GET] bank.com\Accounts -> returns all accounts
• [GET] bank.com\Accounts\3456 -> returns 3456 account details
• [POST] bank.com\Accounts\3456 -> updates account# 3456
• [DELETE] bank.com\Accounts\3456 -> delete account# 3456 soft or hard or whatever

However, I still have to support other operations that don't fall into the CRUD operations group. Operations like:

• deduct tax
• make account dormant
• change account type and apply charges
• and many others that don't change much in the resource but trigger a chain of actions.

If REST only allows the nouns and no verbs, it does not make sense to use edit (PUT) to initiate these actions. My question is, how to expose other functionalities that don't correspond semantically to any of the HTTP methods listed above?. What is the recommended way?

Edit: Check the following videos:

• Designing Beautiful REST + JSON APIs
• How to design a Good RESTful API

They clearly mention that never use API like

• [POST] bank.com\Accounts\3456\Freeze -> Makes account# 3456 dormant

• [POST] bank.com\Accounts\3456\Tax\Withholding -> applies tax to
  account# 3456

and since REST API returns a JSON document, an update should send a JSON document back. so what about those calculations that don't change the actual detail but initiate actions?

In such case how does the REST API, a nicely designed one, allows such calculations? basic CRUD operations are simply not enough. Either the client does the calculations and updates the account document. but that is risky and all transaction synchronization would be a nightmare.

Obviously, this is not the first time this question is asked and there are many solutions (like make the RPC-REST API) but what I asked is what the good way of doing this? there are no specs. there are no standards. so how does the world solves this issue?

Answer 1

HTTP is an application protocol, whose application domain is the transfer of documents over a network -- Jim Webber.

The key idea of REST is that you pass documents (messages), like you would passing paper forms around an office. The HTTP methods describe generic semantics of the document transfer, and useful work is a side effect that lives behind that abstraction.

If REST only allows the nouns and no verbs, it does not make sense to use edit (PUT) to initiate these actions. My question is, how to expose other functionalities that don't correspond semantically to any of the HTTP methods listed above?. What is the recommended way?

Think about how you would do it with a web site.

For "make an account dormant", you would probably GET /account/12345, and within the HTML representation of that resource would be a link to a form. You would fill out the form, and submit it, which would POST an application/x-www-form-urlencoded representation of the submitted form document to the server, which would then update the domain model.

Alternatively, you might GET the document, make domain specific modifications to the document in your favorite HTTP capable text editor, and then save your changes, which would either PUT your document back to the server as is, or possibly compute a patch-document and then PATCH to the server a representation of the patch-document.

You don't see the latter approach so much on the web because browsers, not editors, took over the world. But HTTP supports it - you generically upload documents to the web server, and as a side effect interesting things happen in the domain model.

Your REST API is a disguise your domain model wears so that it is indistinguishable from a website.

Check the following videos

I would instead recommend that you start with

• Stefan Tilkoc, 2014: REST I Don't Think It Means What You Think It Does.
• Jim Webber, 2011: REST: DDD In the Large?
• Jon Moore, 2010: Hypermedia APIs