
RESTful thinking considered harmful - Titanous
http://www.shopify.com/technology/5898287-restful-thinking-considered-harmful
======
cletus
Look, I'm not a REST cheerleader by any stretch of the imagination but in REST
terms the OP just doesn't know his ass from his elbow here. Consider:

> POST /orders/42/pay

> POST /orders/42/ship

You don't put verbs in your URLs. This is really REST 101. I highly recommend
_Nobody understands REST or HTTP_ [1]. The above is exactly _why_ you don't
put verbs in URLs. Consider instead:

    
    
        POST /payment { orderId=42, etc }
    
        POST /shipment { orderId=42, etc }
    

is a much sounder RESTful API design.

And in case anyone feels the need to suggest SOAP, I highly recommend the
satiricial (but disturbingly accurate) _The S stands for Simple_ [2].

[1]: [http://blog.steveklabnik.com/posts/2011-07-03-nobody-
underst...](http://blog.steveklabnik.com/posts/2011-07-03-nobody-understands-
rest-or-http)

[2]:
[http://wanderingbarque.com/nonintersecting/2006/11/15/the-s-...](http://wanderingbarque.com/nonintersecting/2006/11/15/the-
s-stands-for-simple/)

~~~
bluesnowmonkey
Maybe you just skimmed the article, or he's changed it since, but he doesn't
say that verbs in URLs was RESTful. He said it was better than RESTful, and
I'm inclined to agree with him.

Having tried my hand at designing REST APIs for typical business systems a few
times, I've noticed that state machines and transactions are everywhere.
Making every resource a noun with the four basic REST verbs leads to a complex
and extremely chatty design, whereas slipping a few extra verbs in here and
there makes the API simpler, easier to understand, and more efficient.

------
debacle
My thoughts:

1\. Most people who think that REST is The Best Thing Evar don't really
understand what REST is.

2\. Most people who think that REST is terrible don't really understand what
REST is.

REST is a tool. It's useful for a lot of things. It can alleviate initial
scalability issues. It can make an API easier to use or require fewer calls.
It can make it easier or more intuitive for someone to learn an API, and it's
very often easier to make changes to a REST API because of the way it is
written.

But it's just a tool, and if you can't grok that, you're probably a tool as
well.

~~~
ajross
So only true scotsmen aren't tools? I'd argue that if a concept is so badly
explained that _both_ its most zealous proponents and antagonists are
mistaken, that perhaps it's not such a useful design concept in the first
place.

I mean, who could possibly be confused about what the transfer of
representational state means?

~~~
czzarr
since when does a concept need to be easy to explain for it to be great? Ever
heard of general relativity or quantum physics?

~~~
ajross
Those are laws of nature, not design paradigms. They have different (almost
opposite) metrics for "great". Relativity (both variants) and QCD are "great"
precisely because they were discovered and characterized _in spite of the fact
that they are counterintuitive and difficult to visualize_.

Good software design, on the other hand, is all about _human communication_.
And a design paradigm that can't be communicated easily has less value than
one that does.

------
webjunkie
"The RESTful thinker may design both the payment of an order and the shipping
of an order both as updates"

Maybe this thinker got it wrong. How about POST /orders/42/payment to create a
payment object?

~~~
hsuresh
Yup. The author is wrong in his assumption. You can always model the "process"
parts using a resource(payment resource as against pay, transaction as against
credit/debit etc).

~~~
wvanbergen
My point is not so much that REST is wrong, but that RESTful _thinking_ can be
harmful if it comes before thinking about the process you're supporting.

~~~
hsuresh
Ok, but what is RESTful thinking?

The way i think about REST is this: here is my stateful application, how can i
make it available over HTTP/REST. So i start identifying resources. Most of
them are easy - they map to your domains models. But some of the operations on
some of the resources are quite important to my application (eg: ordering
products, making a payment etc), so i consider creating separate resources for
them.

It looks like you are referring to modeling your stateful application when you
talk about RESTful thinking.

~~~
richardlblair
That's a very good question, what is RESTful thinking?

I personally think so many of us are misguided in our think when it comes to
RESTful APIs. In order to make good design decisions for your API you must
understand how the users of your API perceive RESTful APIs. In order for you
to understand how the users of your API perceive RESTfuls APIs you must
consider how the masses (within your target audience) understand RESTful APIs.

Whether your interpretation of RESTful APIs is right or wrong does not matter.
What matters is that people can use it. In order for people to use your API it
must be easy to understand. In order for it to be easy understand it must be
well documented and consistant.

Therefore RESTful API design must be approached on a case by case basis. You
must understand your users, their knowledge base, and how capable they are.

wvanbergen: Interesting article. It was thought provoking at the very least.

------
crewtide
REST is a great starting point for an API, but generic REST interfaces (in
Rails, Django, or any other framework) are relied on too heavily. I'm
especially interested in mobile APIs, which have very specific considerations
that REST doesn't answer well.

Building a generic data back-end for mobile is very hot right now, with lots
of funded startups in the space. Some of them are just offering a REST API,
which frankly any Rails or Django developer could produce in about 10 minutes.
Mobile APIs need to be different, mostly due to slow or non-existent
connections, and require additional thinking. More details here:
<http://ow.ly/9YMrM>

Anybody know of any mobile back-end providers that are thinking innovatively
about this? I've consulted a few of these startups and they all seem hesitant
to make any choices that go beyond REST...but as far as I'm concerned,
offering a generic solution for something that mobile devs have to develop
every time they create an API would be well worth it. A simple example is to
accept a guid for every created object and return that guid in the response.
It's something you have to do to know that the object has been sent
successfully to the server, so why make the developer code it every time?

~~~
beza1e1
I do not think your blog examples goes beyond REST. You just need to represent
different resources. For example a "title list" or "article set".

~~~
div
That, or a nice way of using different mimetypes to indicate which
representation you want.

Also, http status codes perfectly solve the problem of needing to know wether
an object was sent to the server successfully. No need to reinvent the wheel
and mess with guids imo.

------
RyanMcGreal
> POST /orders/42/pay

> POST /orders/42/ship

But "pay" and "ship" are actions, not objects, so it doesn't make a lot of
sense for them to be represented as URLs.

~~~
dalore
> POST /orders/42/payment

> POST /orders/42/shipment

Fixed?

~~~
Roboprog
Pretty close. If you really want to make the process "safe" (idempotent, to
avoid double posted payments), you might actually have to do something more
complicated such as:

GET /order/42/payment/new (returns "3", for example)

PUT /order/42/payment/3 (supplying content for payment info and amount)

Re-issuing the "PUT" (in case confirmation was lost? user double clicked
"submit"?) would simply resend the same value, thus, an "idempotent" action.

Viewing this particular payment is simply:

GET /order/42/payment/3

Without the "3", who knows which payment you would get? (unless you got back
the list of all payments on the order so far)

I'm not sure if this an argument for or against REST, but I'd sure hate to see
a SOAP example typed into a "comment box" in a discussion forum :-)

~~~
pfraze
Good point. I wonder, though-- could you make /order/42/payment the _only_
payment resource related to /order/42, so the ID isn't needed? (PUT
/order/42/payment)

If the payment doesn't cover the bill, you could have the PUT respond with a
link to /order/42/payment/remaining/1, then (if needed) continue with
/remaining/2, and so on.

That would avoid the danger of a gap between your id GET and the payment PUT.

------
chrisdinn
Small thing, but when the author attributes REST to Robert Fleming, I believe
he actually means Roy Fielding.

~~~
wvanbergen
Thanks, will fix.

~~~
nandemo
There's no link for "protecting attribute mass-assignment in the controller
vs. in the model".

~~~
wvanbergen
Must have disappeared when I transferred the article. Fixed, and thanks for
reporting.

~~~
nikcub
transferred the article? you write blog posts in word?

~~~
wvanbergen
Textmate.

------
MatthewPhillips
Can we please kill the "considered harmful" meme?

~~~
jerrya
_X considered harmful_ is one of computing's oldest memes, 44 years old this
month, and was well sort of co-created by two of its foremost computer
scientists. (Dijkstra and Wirth)

As memes go, it has a long history.

<http://en.wikipedia.org/wiki/Considered_harmful>

~~~
MatthewPhillips
Yep, that's probably the worst thing about the meme. Because the original was
so famous, all others piggy back on it, giving their own arguments some amount
of weight.

(off-topic, but goto statements being harmful has been debunked several times
over).

------
strictfp
The writer seems not to consider several other models such as

PUT /orders/42/payed or POST /orders/42/paymentprocessor

, which in my eyes would be both restful and true to the business model.

------
hkarthik
_Ship with a state machine implementation by default, and a generator for a
state machine-backed process model. Be opinionated!_

I think this is the most compelling take away. I learned how to use the
state_machine gem in my current job, and it's an invaluable tool for going
beyond CRUD and building real process models.

~~~
headbiznatch
State machines are excellent, but this comes up every so often on HN and I've
come to respect the observation that state machines become very difficult to
change.

They particularly rock for games, where the universe is unlikely to suddenly
add new interactions or change fundamental laws, but in an evolving business
application with requirements that perpetually jag, they can be a source of
great pain.

EDIT: After thinking about this a bit more, I realize the state machine use is
in reference to an API, which probably should be approached with a certain
sense of immutability. I still think that in general, using them outside of
games should be approached with serious fore-thought to the potential for
change in your requirements.

------
iamleppert
Is it just me or are these "considered harmful" articles becoming way too
cliche? When I see one, I immediately become suspicious of it's content and
distrust it as I've come to associate it with some sort of inflammatory
headline or flippant way to dismiss legitimate conversation.

------
sgonyea
tl;dr

