News for hackers. Stuff that matters.
Re:REST Anti-patterns by fzilla on Monday September 12, 2016 @10:54AM (#12480170)
Yeah I'm saying this is wrong :\

This isn't how REST is supposed to work

Re:REST Anti-patterns by goostavos on Monday September 12, 2016 @11:19AM (#12480452)
Ah, and therein lies the classic problem. Nobody is doing REST "right," but I'm yet to see anyone point to a de-facto example.

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.

Re:REST Anti-patterns by meddlepal on Monday September 12, 2016 @01:39PM (#12481809)
There is a lot ceremony with "REST". Considering REST is architectural pattern and not even an HTTP-specific one I find it very suspect whenever someone says REST API's must use particular HTTP methods or structure URL's in a specific way.

Conventionally that is true and it certainly reduces friction in your API by adhering to common conventions.

Re:REST Anti-patterns by electrotype on Monday September 12, 2016 @12:02PM (#12480828)
Reminds me of Agile...
Re:REST Anti-patterns by blowski on Monday September 12, 2016 @10:58AM (#12480220)
Can you give an example here of how you think it should work, please. This is one area of REST with which I have a lot of trouble.
Re:REST Anti-patterns by 33degrees on Monday September 12, 2016 @11:32AM (#12480579)
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.

Re:REST Anti-patterns by jchoca on Monday September 12, 2016 @01:27PM (#12481702)
A less related question: how do you decide between adding something as a property vs. creating a new subresource?
Re:REST Anti-patterns by 33degrees on Monday September 12, 2016 @02:10PM (#12482139)
Good question, I guess it's pretty much the same as deciding if something is a new field or a new table in a database?
Re:REST Anti-patterns by blowski on Monday September 12, 2016 @11:40AM (#12480642)
Your PATCH example makes sense, so I should do something like (depending on your opinions of how to do PATCH requests):

    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=10
Re:REST Anti-patterns by 33degrees on Monday September 12, 2016 @11:56AM (#12480767)
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.

Re:REST Anti-patterns by blowski on Monday September 12, 2016 @12:23PM (#12481025)
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.

Re:REST Anti-patterns by dragonwriter on Monday September 12, 2016 @12:29PM (#12481095)
> 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.

Re:REST Anti-patterns by blowski on Monday September 12, 2016 @01:14PM (#12481560)
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.

Re:REST Anti-patterns by 33degrees on Monday September 12, 2016 @01:54PM (#12481982)
Why not

    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?
Re:REST Anti-patterns by blowski on Monday September 12, 2016 @02:00PM (#12482047)
I guess because it's not how I talk. I say "I'll print this document", not "I'll send this document to the printer".

I don't have a print queue because nobody has ever asked for one or shown the need for one.

Re:REST Anti-patterns by dragonwriter on Monday September 12, 2016 @03:09PM (#12482702)
There are lots of aesthetic preferences like this about URLs, but calling them issues of "RESTful"-ness is just plain wrong. REST not only does not prescribe an approach to structuring URLs, it specifies a role for identifiers (URLs in the usual case of HTTP) which makes their construction irrelevant, and worrying about it contrary to the central concept of REST.

> 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.

Re:REST Anti-patterns by 33degrees on Monday September 12, 2016 @12:55PM (#12481369)
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.

Re:REST Anti-patterns by simonh on Monday September 12, 2016 @12:50PM (#12481309)
The url might be very similar, but the way it is used - what methods you call on it and with what content, is completely different.
Re:REST Anti-patterns by qyv on Monday September 12, 2016 @11:20AM (#12480459)
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.
Re:REST Anti-patterns by blowski on Monday September 12, 2016 @11:27AM (#12480522)
So I would make a request like:

    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=10
Re:REST Anti-patterns by qyv on Monday September 12, 2016 @12:47PM (#12481279)
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.