-1

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:

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?

  • use POST and make a RPC style request – Ewan Mar 30 at 10:49
  • isn't that something that is not RESTish? so basically we have to resort to rpc style. – Simple Fellow Mar 30 at 11:09
  • 1
    make up a new http verb and use that – Ewan Mar 30 at 11:14
  • One thing to think about: Command-Query segregation. Think about it. You don't have to make everything REST or nothing at all. – Laiv Mar 30 at 13:02
  • 1
    Not sure why this question isn't being well received. – candied_orange Mar 30 at 13:29
3

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

  • I have updated my question and added details. see if that helps or let me know – Simple Fellow Mar 31 at 5:41

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.