4 ms·

"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 /ord

"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 15y 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-understands-rest-or-https http://blog.steveklabnik.com/posts/2011-07-03-nobody-underst... transaction resources.
hsuresh 15y 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).
- wvanbergen 15y 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.
  - chrisdinn 15y ago
    I think this is a fair point. REST is all about resources and representations, which makes modeling simple CRUD actions on domain objects very easy. However, modeling application processes effectively is harder and requires deeper thought and a more thorough understanding of REST. 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.
  - hsuresh 15y ago
    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 15y ago
      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.
    - jaylevitt 15y ago
      I think by "RESTful thinking" he means "cargo-culting the Rails RESTful scaffolding".
beza1e1 15y 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 15y 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.

masklinn 15y 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-understands-rest-or-https http://blog.steveklabnik.com/posts/2011-07-03-nobody-underst... transaction resources.

hsuresh 15y 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).

wvanbergen 15y 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.
- chrisdinn 15y ago
  I think this is a fair point. REST is all about resources and representations, which makes modeling simple CRUD actions on domain objects very easy. However, modeling application processes effectively is harder and requires deeper thought and a more thorough understanding of REST. 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.
- hsuresh 15y ago
  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 15y ago
    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.
  - jaylevitt 15y ago
    I think by "RESTful thinking" he means "cargo-culting the Rails RESTful scaffolding".

beza1e1 15y 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 15y 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.