One way to approach it would be to have consider deposits, withdrawals, and transfers as subresources of a specific account. So you could POST to "/account/4502278/deposits" to create a new deposit, which would then live at a URL such as "/account/4502278/deposits/87162". And instead of separate subresources for all of these different transaction, it could just be one "transaction" subresource.
In the case of closing an account, it depends on what actually happens when you do so, but I would normally have a "status" attribute and use PATCH to update that.
I personally think that's less readable than the original, but I agree that it seems to more closely fit the REST standard.
With the deposit, I don't really understand what's changed here from the original. To me, it just looks like deposit has been pluralised, and everything else is the same:
I would simply PATCH { "status" : "closed" }, as that's how PATCH works in rails.
Regarding the deposits, the difference is that 'deposits' is a collection of deposit resources vs 'deposit' as a verb. I think in this case it makes a lot of sense to do it that way, as you can then GET /account/12345/deposits and see all the deposits ever made.
OK, so the original one used a verb at the end of the URL, whereas it should have used a noun. In practice, this wil often means that the URL is almost identical - here for example, it will be:
POST /accounts/12345/deposits
instead of:
POST /accounts/12345/deposit
Perhaps your example would be more obvious if it had different terms, where the noun and verb were more distinct - maybe 'game' and 'play'.
Even then, from experience, you end up with some horrible URLs just so it's RESTful. While I try to follow REST, I balance it against making the API readable by human beings.
> you end up with some horrible URLs just so it's RESTful
No, you don't. RESTful applications use URLs as opaque identifiers, and communicate all information via resource representations. Communicating information via resource identifiers is decidedly not-RESTful, so any particular URL structure chosen to communicate specific information in the URL is, ipso facto, not RESTful.
I'll give a specific specific example from my own experience of building an intranet. I had documents that people could print.
POST /documents/12345/print
To me, while this was not RESTful, it was the most readable way I came up with. When I asked somebody who had more experience with REST than me, he suggested I build the URL like this:
POST /users/123/print-jobs
url=/documents/12345
Doing this, I would have to add validation to make sure it was a printable URL. Also, there was no corresponding GET request, so it seemed pointless. And it made the code weirder, as the 'print' action would be separated from the rest of the actions on documents.
So how would you do it instead? Or you would do it the same way, and just not worry about the problem?
It seems that consensus on how to do REST breaks down when you have custom verbs.
Yes, it should have been a noun, because a URL is a Uniform Resource Locator, and a verb is not a resource. HTTP methods are for verbs. Sometimes this can lead to strange URLs, but applying the noun/verb rule consistently does simplify things.
One thing that helps is not nesting resources too deep, to avoid having really long URLS.
For the deposit/withdrawal/transfer set, depending on the specifics of how they are actually moving the amounts around, would likely be best served as their own resource. Since a deposit/withdrawal is just a transfer anyways, just having "/transfer" would be likely be good. The connotation here is that the client is creating a transfer on the server. The body for this request could take the relevant account numbers (you need two accounts), and the sign on the amount would denote if the amount is being deposited or withdrawn.
Having the /account/:accountid/transfer is not a terrible idea, but I would avoid it because the transfer resource is able to stand on it's own with making it tied to a single account resource.
The key point though is that 'transfer' is the resource to perform all three of the original deposit/withdrawal/transfer actions.
In the case of closing an account, it depends on what actually happens when you do so, but I would normally have a "status" attribute and use PATCH to update that.