If "status" is just a property on the accounts resource and doesn't have further meaning, I would tend to agree with you.
If "close" is an action or activity that acts upon an accounts resource, then his approach makes sense.
Since the context is an account that we "need to close," I would assume the author is talking about something more complex than a database field. It's probably a workflow that initiates other actions and workflows, maybe even requiring additional review. I'd want to see/understand the requirements more fully before I started down either path.
More specifically, it shouldn't have to matter to consumers. Because of the way REST and HTTP work, clients intuitively understand retrieving and modifying resources (via GET, POST, PUT, PATCH and DELETE). But they don't understand interacting with special-purpose endpoints (POST always implies "make a new thing" so it's weird in this context).
Your consumers should not have to learn weird idiosyncrasies in your API because you let your data model bleed into the interface.
An API is a representation of business workflows and processes. The more accurately you describe or map those to the real world processes, the better your and your consumers' understanding will be.
It seems like we spend a lot of time designing object relations that map a domain, but maybe not so much mapping domain-specific actions.
Or would you consider all of the above bad practice?
If you're speaking HTML it can be as simple as:
<form action="/close-account?acc_number=12345" method="POST">
<button>Close Account</button>
</form>
Or even: <form action="/close-account" method="POST">
<input type="hidden" name="acc_number" value="12345">
<button>Close Account</button>
</form>
If you're speaking Siren (https://github.com/kevinswiber/siren): {
"actions": [
{
"title": "Close Account",
"method": "POST",
"href": "/close-account",
"type": "application/x-www-form-urlencoded",
"fields": [
{ "name": "acc_number", "type": "hidden", "value": "12345" }
]
}
]
}So what? REST is an API [0]. It's the public interface you expose. What you do behind the scene in your data model is, or should be, irrelevant to the API. Sometimes you'll map your data model practically one-to-one to the REST API, but there are times when I do significant logic in controllers before mapping the result of that logic to a resource. As long as the API is resource oriented and follows good REST practices, it's all good.
0. OK, REST is one way to expose an API, since the wording I used is not amenable to some people.
No, REST is an architectural style.
For APIs. But yes, we can argue semantics now. My point is, REST is a way to expose an API.
Right. Particularly, if a closure request is a thing that has its own status, identity, and associated data elements, which one might wish to examine and interact with (and, while its possible that such interaction might not be possible for external users with privileges only on their own accounts, it might well be possible for internal administrative users), then it makes sense as a resource, rather than a data element buried in representations of another resource.
Without full behavioral requirements and domain model, you really don't know what makes the most sense.
POST /accounts/4402278/close
You would have something like
POST /accounts/4402278/closures
{"rel": "deposit", href: "/account/4502278/deposit"},
{"rel": "withdraw", href: "/account/4502278/withdraw"},
{"rel": "transfer", href: "/account/4502278/transfer"},
{"rel": "close", href: "/account/4502278/close"}This isn't how REST is supposed to work
Fielding's dissertation isn't a spec, which pretty much means everyone can come up with their own little slice of how it should be done and then say they're doing it right.
The true rule of REST: whoever is blogging/commenting about it at the time is doing REST right, all others are confused and incorrect.
Conventionally that is true and it certainly reduces friction in your API by adhering to common conventions.
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.
PATCH /users/123
[{ "op": "replace", "path": "/accounts/12345/status", "value": "closed" }]
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:
POST /account/12345/deposits
amount=10Regarding 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.
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.
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.
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.
POST /documents/12345/print-jobs
And you say there's not corresponding GET request, but maybe there should be? Perhaps you'd want to list print jobs, get the status of a particular job, and maybe cancel it?I don't have a print queue because nobody has ever asked for one or shown the need for one.
> 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
What was the logic: neither version is more RESTful, even if you ignore the role of URLs in REST and adopt what seems to be the usual definition of RESTful URLs used by people who use any coherent definition: the URL represents some logical hierarchy of resources.
In this case, your original "POST /documents/12345/print" implies a collection of print requests (I'd probably call it "prints" or "print-requests" rather than "print", but that's a minor quibble) pertaining to a particular document, to which a new request is added when the user wants to print the document. Sounds perfectly sensible.
The alternative offered suggests a list of print jobs belonging to a user, which is also sensible. But there is no strong reason to prefer one over the other.
And if you were actually RESTful, it wouldn't matter, because your resource representation for the print job/request would actually include both the URL and the user. (And maybe status and other information.)
Both your original (with no representation) and the alternative (with the user in the URL and the document in the resource representation) aren't RESTful because they have information that logically belongs to the resource in the URL and out-of-band context rather as part of the resource. But that's not a matter of URL construction, its fine for a URL scheme to correspond to information about the resources, as long as the information is actually still part of the resource.
> It seems that consensus on how to do REST breaks down when you have custom verbs.
If you have real custom verbs, then you may need to extend HTTP's set of methods (it wouldn't be the first time that has been necessary -- PATCH isn't a base HTTP/1.1 method.)
But there is a difference between a generic action on resources of the type represented by an HTTP method and an action-in-the-domain, and it sounds in your case "print" is an action in the domain, which is an event which should have a corresponding noun -- and thus a resource representation -- in the model. But while URLs are inherently hierarchical, real relationships in real domains are often webs, and so there's not one true way to map it into a hierarchy.
One thing that helps is not nesting resources too deep, to avoid having really long URLS.
POST /transfer
from_account_id=12345&to_account_id=67890&amount=10
Perhaps I've misunderstood your comment, as I don't really understand why this is better than the original: POST /accounts/12345/transfer
to_account_id=67890&amount=10
or even: POST /accounts/12345/withdraw
amount=10The key point though is that 'transfer' is the resource to perform all three of the original deposit/withdrawal/transfer actions.
Of course its right. Read the POST spec. POST is for processing data. Its up to the server to what is processed how. If the POST is for closing a bank account, it is valid. I think, my bank would need verify a lot of things before I can close my account with a single click. So the operation cannot be idempotent and thus requires a POST.
I mean, if you are fine with setting just a flag in your bank, you can be fine with a PUT. But I will not become a customer of your bank.
Again, this is the interface to a complex data model, and I would be wary of using a bank that dumped all of its security and process controls into one endpoint's controller.
Also - closing an account is an inherently idempotent operation, no? It can only be closed once. If I request that a closed account be closed again, it stays closed.
Account status (open, closed, suspended, whatever else) is a property of the account, in the same way that the account owner's name is a property of the account. If you went to all the trouble to represent each account as its own resource, which I assume responds correctly otherwise to GET, POST and PUT requests, why is this one property special enough to get its own endpoint? Why would you not just PUT or PATCH the account to change the "status" property to "closed"?
In my experience, programmers typically break best practices in this way when there is special logic that needs to happen when the property changes. In other words, PUT is fine as long as it's only overlaying new data and not triggering other processes, but closing an account kicks off a whole host of internal processes at the business, so it seemed reasonable to someone to make it a separate endpoint.
This either represents a friction between good API design and what programmers find reasonable ("I have to make a bunch of special things happen, so I'll bundle them into their own function and expose them"), or the API framework isn't flexible enough to supply hooks to insert logic at field-level changes, or both.