Page 112 - Question about figure 5-4

[RESTRookie]

Hi,

I'm currently reading the book page by page to understanding the total package for building a REST server. However I stumbled upon a question about one of the figures used in the book. On page 112, in figure 5-4, the application protocol for Restbucks has been explained in transitions, business logic and events.

I'm questioning the second "POST" transition, because it actually updates an existing order and uses an order identifier to do so. Whenever we do an update on an existing resource like the order in the example, we should use the "PUT" verb right? So why is "POST" being used for an update in this figure? Is this an error or am I looking at this from the wrong perspective?

Regards,

RESTRookie

[Jim Webber]

Hi,

This is a common pattern with a stable entry point URI from where the rest of the application is triggered.

In this case the resource itself remains static (it's the entry point after all) but interacting with it via POST will always redirect you to a newly created resource that represents your order.

Does that make sense?

Jim

[RESTRookie]

Hi Jim,

Thank you for your response.

Yes, that's exactly what I thought when I looked at the schematic. The first action describes how a new order is created, the second one describes how the order gets updated by using POST with new information which doesn't sound like proper use of the HTTP verbs. On page 114 there's a further explanation about why POST is used instead of PUT, but I'm still questioning why.

According to the strict guidelines for using PUT, it's not allowed to update parts of a resource without using the full dataset in the resource. So this would mean the whole order should be PUT to the resource, instead of just the order status. Page 114 explains that it would also be possible to use PATCH to update a single part of the resource. However, I wonder if using a GET before using a second POST, would make a difference. Because using a GET to read all the information from the order, would make it possible to use PUT and update the order in full right? Since the verbs used with the HTTP protocols have pretty clear purposes, it doesn't sound RESTfull to use POST instead of PUT to update/change an existing order.

Further along in the book protocols are being described. What I don't understand, is why it would be possible to update the order (resource) before a GET has been performed. Why would you suggest a link to edit an order after creating a new one? Isn't the logical path to first retrieve the order and then to decide whether to update the resource or not? It might even be possible that an internal (business) process might have changed the state of the resource, which could lead to dataloss without using GET (and possibly ETag or something similar).

So if I had to design the schematic, I would take the path of POSTing a new order, GETting my newly created resource by following the only suggested link (protocol), followed by PUTting an update of the order to the resource containing the status update and so on.

Am I totally missing the point and is my way of thinking just another route to the same result?

Regards,

RESTRookie

[Jim Webber]

Hello,

> Yes, that's exactly what I thought when I looked at the schematic. The first action describes how a new order is created, the second one describes how the order gets updated by using POST with new information which doesn't sound like proper use of the HTTP verbs. On page 114 there's a further explanation about why POST is used instead of PUT, but I'm still questioning why.

Because nobody really knows whether it's PUT or POST. The two bastions of the Web Mark Baker and Mark Nottingham themselves even disagree the last time I canvassed them.

It's not improper to use POST (since post is a catch-all) but whether or not it is as constrained as it could be is up for debate. In RiP we made our call: POST.

> According to the strict guidelines for using PUT, it's not allowed to update parts of a resource without using the full dataset in the resource.

True, hence the above.

> So this would mean the whole order should be PUT to the resource, instead of just the order status.

You -as the customer- don't get to change the order status. There is no API affordance for that. Order status is something that is a side-effect of some back-end processing.

> Page 114 explains that it would also be possible to use PATCH to update a single part of the resource. However, I wonder if using a GET before using a second POST, would make a difference. Because using a GET to read all the information from the order, would make it possible to use PUT and update the order in full right? Since the verbs used with the HTTP protocols have pretty clear purposes, it doesn't sound RESTfull to use POST instead of PUT to update/change an existing order.

Actually you'd use etags if you wanted conditional update. And prefer PUT over POST where you can. However in this case I'l reiterate the customer cannot change the order status.


Jim

[RESTRookie]

Hi Jim,

Thank you for your response. I think I'm starting to get it. :)

Regards,

RESTRookie

[Josh Graham]

100% agree.

> --
> You received this message because you are subscribed to the Google Groups "restinpractice" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to restinpractic...@googlegroups.com.
> For more options, visit https://groups.google.com/d/optout.

[Mitch Trainham]

This really doesn't make much sense. The way you are describing it, and the way the book describes it on page 114, any time even one single property of a representation (including links) can't be modified by the client, that means you don't use a PUT. How often does a server return a representation of a resource in which every single property, including all links, can be updated by the client? This pretty much makes everything a POST, and renders PUT useless. After all, how does it even make sense for the client to update links? The server controls which links show up, and what URI it links to, and the client transitions state based on that. The client doesn't update links.

[Chris Margraff]

A POST is a CREATE and a PUT is an UPDATE from the client’s perspective. It has been a long time since I read it, but I think the book here, in my opinion is deviating from “in practice”, because “in practice” the way writes are handled and backing storage schemas have nothing to do with the schema contract on the front end. Consider a geographically sharded database. We can’t expect the REST client to be smart enough to determine where we’re going to store data, but we may leverage properties in the front end schema or its HTTP wrapper to help make that determination.

 

The way you are talking about REST here is more of an OData implementation. OData is a CRUD framework on top of rest where the storage implementation and the REST schema contracts line up. There are data-focused services like this and there are workstream (application) focused services that are views of back end data. This book does not differentiate between the two, but “in practice” (again), you build your interface to satisfy an audience. Putting an OData schema on a coffee service would not make sense, because over time you will be sending far more fields than you actually need, and it will shift your business logic to the front end (danger).  Use storage-specified schemas such as OData for back-end integration services and build custom application-scoped schemas to meet front-end needs.

 

Hope this helps!

--

You received this message because you are subscribed to the Google Groups "restinpractice" group.
To unsubscribe from this group and stop receiving emails from it, send an email to restinpractic...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/restinpractice/dcabc454-06bb-4043-b751-0a1c1a97729f%40googlegroups.com.

 

[Mitch Trainham]

A POST is a CREATE and a PUT is an UPDATE from the client’s perspective

That's my point. It doesn't make sense for the client to only use PUT in updates where the client has to be able to update each and every property, including links.

The book's mission is to explain REST in an accessible way. You can come up with all kinds of complex reasons to defend how it may be possible to defend the book's example, but that's not the point. The book shouldn't be using examples like this that clearly contradict early parts of the book, and if they do, they should at least explain it without creating more questions than answers. 

To unsubscribe from this group and stop receiving emails from it, send an email to restinp...@googlegroups.com.

[Chris Margraff]

“In Practice” is the key.  In practice, you need to make implementation decisions that solve both front **and** back end problems, and you don’t always get the call when you’re building other people’s apps. Look at REST as a front end spec, and think of these HTTP methods more aspirational – how you want the client to perceive the transaction.

 

Remember that REST is an architectural style, not a strict implementation protocol. There is not one correct REST way. I think you’ll benefit from digging into Fielding’s original work (http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm), particularly his commentary on layered implementations. A front-end GET, POST, etc does not impose some kind of regulatory requirement on the back end. Also please note that Fielding’s [great] early work does not address modern topics like schema versioning and client-side vulnerabilities, and so we are left to our own devices to deal with these kinds of things.

 

If you need a strict protocol, look into OData or (lord help you) SOAP.

To unsubscribe from this group and stop receiving emails from it, send an email to restinpractic...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/restinpractice/5041dc87-c1e5-4991-8b4a-800fd11fecb6%40googlegroups.com.

 

[Mitch Trainham]

I don't understand why I have to explain this but here goes. In the real world you are correct. REST principles need to be weighed against the practical business use case, and exceptions need to be made. In the context of reading a REST book to understand what REST is, how does it make sense to introduce examples that are some part REST and other parts "practical exceptions to REST"? One first needs to follow examples of strict REST to be able to understand when and when not to use REST strictly. Is this not common sense to you?

To view this discussion on the web visit https://groups.google.com/d/msgid/restinpractice/5041dc87-c1e5-4991-8b4a-800fd11fecb6%40googlegroups.com.

 

[Jim Webber]

> The book's mission is to explain REST in an accessible way. You can come up with all kinds of complex reasons to defend how it may be possible to defend the book's example, but that's not the point. The book shouldn't be using examples like this that clearly contradict early parts of the book, and if they do, they should at least explain it without creating more questions than answers.

Notwithstanding we authors are fallible and we must own the mistakes, it seems to me there’s an opportunity for some folks to write a better book than RiP now that we’ve had an additional 10 years of learning.

I’ll volunteer to review :-)

Jim