intertwingly

Congratulations! I’m eagerly looking forward to receiving my copy of the book and will not be surprised if other similar and overly positive reviews will continue to pop up once people have gnawed through it. :-)

Sam Ruby and Leonard Richardson have just published RESTFul Web Services. I haven’t had a chance to read it yet, but will see if I can wheedle an author copy out of my publisher. Knowing Sam, it should be both comprehensive and complete. Seems to be...

Jon Udell, rightly so, is getting excited about the new book RESTful Web Services , by Leonard Richardson... [more]

Trackback from Alex Barnett blog

Having design REST services in the past, and working on one now, I eagerly ordered this book and started reading last night. 

I immediately jumped to the section on URI design, and like how you described the tension between friendly (unstable) and non-friendly (stable) names (with references, no less).  I then jumped to the appendices on status codes and headers.  The appendices alone are reason enough to buy the book.

Great job - well written, and very welcome.

Jon Udell, rightly so, is getting excited about the new book RESTful Web Services , by Leonard Richardson and Sam Ruby - a book I myself got excited about in November ( REST Web Services and ROA ) when I wrote at the time: "My bet is that...

Great book (so far), but since when is HMAC-SHA1 (as used to authenticate to S3) "public-key cryptography"!!  [page 65, 2nd paragraph]

Sam,

I just finished the book you co-authored (the other partner in the authorial “I") with Leonard Richardson. I really enjoyed reading it and learned a lot. A few questions. Not sure if this is the place to post, but here it goes.

1) You discussed the practice of serving up a form along with a representation so a client can have something to start with when doing edits (p.g. 161). Alternatives would be providing some sort of schema or natural language description. This assumes that the resource exists. What about a form that is used to create a resource? In this case, what is the resource that is being requested? I suppose you could think of a form as a resource, but this doesn’t seem to fit when the client posts the form to create a resource. Client is not creating a form; he’s creating a resource whose details are being transmitted as an HTML form. Would be curious how frameworks like RoR handle this.

2) How would a partial edit or a validation step be represented in REST? Take a simple example. An address form that is dynamically modified given a client’s choice of country. When a client updates the country field, the client should send a message to the server with the form values; the server should answer back with the some sort of diff of the form or a new form with the additional fields. This isn’t a true edit, because nothing is committed. I thought of using the Expect HTTP header to simulate a real edit, but I’m not sure if this is a misuse of HTTP given there would be something in the request body (ie the current state of the form) and something in the response body as well. The current application I’m developing has lots of these hooks that require form state but are idempotent (e.g. dynamic pick lists based on form selections and security role, making fields required or read-only). How does REST work in this interactive, form-based model? The impression I got from the book is that REST is more suited for clients that are smart enough to work on the representations themselves, maintaining application state, etc., until they’re ready to do the final submit, which is either a POST or a PUT. I think subversion is an interesting comparison. The subversion client supports operation like "add”, “remove”, “rename”, but under the covers it’s just keeping a record of these operations until the final “commit” action is called, at which time all the accumulated edits are submitted. The subversion client can maintain this state itself, but what if the server needed to provide feedback from actions that led up to the final commit? How would an action like this fit into the uniform HTTP interface?

Regards,
Brent

Brent, I’m not certain I fully understand your first question.  A form, or a schema, is a resource that you GET.  That resource contains instructions on what other resource one will typically GET/POST (or possibly even PUT/DELETE, depending on the form/schema language) additional requests.  In other words, you don’t “post a form”, you “get a form”, and then create new resources by issuing a POST request with a representation of that resource.

As to how to handle “proving feedback from actions that led up to the final commit”, the key constraint that one needs to keep in mind is “each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server.” (section 5.1.3 from Roy’s thesis).  For some systems, this may represent an unacceptable tradeoff, and a more tightly coupled solution may be required; but in many other cases, respecting this constraint is key to scalability.

Sam, your response on the first question makes clear the distinction I was fishing for. You get a form and the representation of that form may also contain instructions for manipulating other related resources. For some reason I was thinking that a get of a resource should only give you instructions on posting/putting THAT resource. Thanks for clarifying.

As for the second, the scenario I had in mind would still satisfy the requirement that “each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server.” The client would submit a form, but instead of committing that form to persistent storage, the server would modify the temporary representation and send it back to the client for further processing. The new representation might have additional fields, a validation message, etc. Sort of like a “preview” step for a wiki page instead of the final “save”. Does that make sense?