RESTful thinking considered harmful

http://www.shopify.com/technology/5898287-restful-thinking-considered-harmful

by Titanous • 14 years ago

97 73 14 years ago

shopify.com

chrisdinn2• 14 years ago

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

wvanbergen4• 14 years ago

Thanks, will fix.

nandemo• 14 years ago

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

webjunkie• 14 years ago

"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?

masklinn• 14 years ago

> to create a payment object?

resource.

Also, not sure what's up with TFA's strawmanning,

    PATCH /orders/42 # with { order: { paid: true  } }
    PATCH /orders/42 # with { order: { shipped: true } }

looks like RPC update calls (hey let's map our Ruby attribute updates to HTTP calls, yay!) more than RESTful calls.

Also, not sure why a payment resource would be conceptually "within" an order (although that's got little to do with RESTfullness): why not POST to /payments?order=42? Which would return a link to e.g. /payments/2345 for your actual payment resource?

Something similar to http://blog.steveklabnik.com/posts/2011-07-03-nobody-underst... transaction resources.

hsuresh2• 14 years ago

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

wvanbergen4• 14 years ago

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.

beza1e12• 14 years ago

Nearly correct. POST does not specify the name of the resource. So you do

  /orders/42 # with { order: { paid: true  } }

And it returns the /orders/42/payment transaction resource.

drsim• 14 years ago

I disagree. Surely an Order HAS Payments, therefore /orders/42/payment POST is more correct. Likewise orders/42/shipment.

Nicely leading on to /orders/42/payments/1.

debacle6• 14 years ago

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.

krober3• 14 years ago

I agree with the "it's just a tool" sentiment in general, but what other great alternatives are there? I haven't had a favorable experience with SOAP, so I can understand why people think REST The Best Thing Evar. This is based on my own experiences, so I may have used SOAP wrong, misunderstood its intentions, etc. Do you have any examples of when SOAP (or another technology) is preferable to REST?

rdtsc• 14 years ago

The "other thing" for us is is RPC and PUB/SUB patterns over sockjs (which wraps Websockets+fallbacks).

REST is a tool. But given an engineer a tool like a hammer and pretty soon everything will look like a nail. Sometimes you need a screwdriver when you actually have screws. Hammering them in will work but it is ugly.

debacle6• 14 years ago

You can write RESTful SOAP, I don't think the two ideas are perpendicular. The problem with SOAP is more implementation than spec - PHP SOAP is different from .NET SOAP which is (slightly) different from Java SOAP, which leads to headaches.

REST is just a style of API. You can write a JSON API that isn't RESTful just as easily, and in some cases a RESTful API is not warranted.

pradocchia• 14 years ago

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

Unnecessary. All tools have a learning curve, a conceptual slope leading to the sweet spot. Being low on the curve does not make one a tool.

debacle6• 14 years ago

I don't believe passing judgement on something you don't fully understand is a good quality to have, even if it gets your blog more hits.

ajross2• 14 years ago

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?

debacle6• 14 years ago

We're getting off track here, so I'm going to recuse myself, but I would argue that the most zealous proponents and antagonists of any concepts are likely mistaken, in some way.

czzarr• 14 years ago

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

RyanMcGreal2• 14 years ago

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

rch• 14 years ago

You hit the nail on the head there. If the author posted a new payment (using whatever metaphor), then a handler could initiate a set of actions in the course of processing <metaphor>.

Maybe this is a real debate in some circles, but I cannot fathom mapping HTTP verbs directly to SQL statements.

kevinpfab2• 14 years ago

Exactly. Having these endpoints instantly turns your API into an RPC-API. This is the start of a snowball of complexity introduced for your consumers.

bad_user• 14 years ago

I understand why that isn't RESTfull, but why is it more complex?

"customers" are used to thinking in terms of actions. You hit this little button here for payment, you hit this other little button here for shipment. And for developers, these are like methods containing business logic belonging to an object.

So where's the problem?

dalore• 14 years ago

> POST /orders/42/payment

> POST /orders/42/shipment

Fixed?

pfraze5• 14 years ago

Yeah.

Roboprog• 14 years ago

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 :-)

pbreit• 14 years ago

Shouldn't it be:

  POST /payment
  order=42

Or:

  POST(or PUT) /order/42
  status=shipped

silon4• 14 years ago

POST /orders/42?pay=1

POST was always about actions, not just resources.

RyanMcGreal2• 14 years ago

An HTTP request has two parts: a resource (URL) and a method. Expressing your method in the resource rather than the, um, method muddles the two.

strictfp2• 14 years ago

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.

crewtide• 14 years ago

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?

j_s• 14 years ago

ow.ly/9YMrM -> http://www.annacallahan.com/blog/2011/06/24/mobile-api-desig...

beza1e12• 14 years ago

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• 14 years ago

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.

hkarthik• 14 years ago

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• 14 years ago

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.

MatthewPhillips3• 14 years ago

Can we please kill the "considered harmful" meme?

DanWaterworth• 14 years ago

killing memes considered harmful.

gmaslov• 14 years ago

Why? When I see "considered harmful" in a title, I know pretty much what kind of article to expect. I think it's a useful shorthand, and that its origins, and the whimsical attitude associated with it, are irrelevant. What alternative title would you suggest for this article?

MatthewPhillips3• 14 years ago

"Why the merits of REST are overstated"

"Considered harmful" is a flippant way to dismiss detractors.

jerrya• 14 years ago

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

MatthewPhillips3• 14 years ago

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

Tobu• 14 years ago

Especially here where it's cheap linkbait for an article whose actual claim seems to be “Gee, REST is hard to get right sometimes”. Not that I like the inflamed rhetoric of an actual “considered harmful” call to arms, either.

cletus• 14 years ago

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

[2] http://wanderingbarque.com/nonintersecting/2006/11/15/the-s-...

jeffmess• 14 years ago

Placing verbs in your Resftul apis resources is wrong, but it just feels so right....

bluesnowmonkey2• 14 years ago

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.

iamleppert• 14 years ago

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• 14 years ago

tl;dr

RESTful thinking considered harmful

Related Stories