RESTful thinking considered harmful
shopify.com
shopify.com
> 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 }
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-...
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.
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.
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.
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.
SOAP is a bit weird because it's both an envelope/delivery mechanism as well as a discovery/interface negotiation methodology.
REST is just straight up a set of interface design principles. It doesn't care what you're delivering, it doesn't care about the channel you deliver it through.
He's saying they aren't perpendicular and also saying they are independent.
Fox Sports has a pretty restful XML API. I can't remember if it's SOAP specifically, though.
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.
I mean, who could possibly be confused about what the transfer of representational state means?
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.
Maybe this thinker got it wrong. How about POST /orders/42/payment 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 } }
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.
I've always thought the key to understanding REST is understanding idempotence. Is HTTP request to mark an order as paid idempotent? If so, a PUT/PATCH should be fine. If not (say, you're actually transferring funds) then a POST should be used. This key principle will help make your URL design choices much easier. In your example, the PATCH API appears idempotent, making the suggested POST replacement sort of confusing to me.
When it comes to modeling application processes using HTTP, understanding which requests are repeatable without consequence and which aren't is very important. It's hard to talk about modeling processes RESTfully without talking about idempotence. It's at the heart of the protocol's design.
RESTful thinking needn't be harmful for application processes as long as you do it effectively.
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.
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.
/orders/42 # with { order: { paid: true } }
Nicely leading on to /orders/42/payments/1.
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?
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.
> 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.
Maybe this is a real debate in some circles, but I cannot fathom mapping HTTP verbs directly to SQL statements.
"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?
GET /orders/42/pay is a verb on a verb. Maybe not complex, but definitely confusing.
That's the most natural mapping, the verb PAY on the object of order 42. Maybe HTTP needs arbitrary verbs instead of a limited predefined set? We'd have to get firewalls and proxies and such out of the habit of processing a request depending on its verb.
To me it seems logical to embrace the ideas of the tool you are using. If you are not utilizing the power of HTTP, why not just use a pure RPC protocol?
I think that we eventually have to open up for more protocols if the web continues to develop into a generic dev platform. In a sense we are already heading in that direction with WebSockets. But since HTTP has been and continues to be such a success, I think that we can atleast try to promote it.
If you use hypertext in the resources to specify the places the client can go, the complexity is severely reduced. However, properly enabling discovery is where most "Rest" APIs fail.
> POST /orders/42/shipment
Fixed?
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 :-)
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.
POST /payment
order=42
POST(or PUT) /order/42
status=shippedPOST was always about actions, not just resources.
"Considered harmful" is a flippant way to dismiss detractors.
As memes go, it has a long history.
(off-topic, but goto statements being harmful has been debunked several times over).
PUT /orders/42/payed or POST /orders/42/paymentprocessor
, which in my eyes would be both restful and true to the business model.
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.
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.