mca blog

below are my notes from the middle section of RESTful Web Services (2007, Richarson and Ruby):

A resource *is* something, so I take an object-oriented approach to designing resources. In fact, the resource-oriented design strategy could be called "extreme object-oriented." (pg. 108)

Whenever I'm tempted to add a new method to one of my resource "classes", I'll resolve the problem by defining a new kind of resource. (pg. 109)

1. Figure out the data set
2. Split the data set into resources
3. Name the resources with URIs
4. Expose a subset of the uniform interface
5. Design the representation(s) accepted from the client
6. Design the representation(s) served to the client
7. Integrate the resource into existing resources, using hypermedia links and forms
8. Consider the typical course of events: what's supposed to happen?
9. Consider the error conditions: what might go wrong? (pg 109-110)

A web service starts with a data set, or at least an idea for one. (pg. 110)

...in a resource-oriented analysis, ways of looking at the data are themselves pieces of data. If you consider an algorithm's output to be a resource, running the algorithm can be as simple as sending a GET to that resource. (pg. 112)

• Predefined one-off resources for especially important aspects of the application
• A resource for every object exposed through the service
• Resources representing the results of algorithms applied to the data set. (pg 113)

It takes a while to get the hang of exposing an algorithm as a set of resources. Instead of thinking in terms of actions ("do a search for places on the map"), you need to think in terms of the results of that action ("the list of places on the map matching a search criteria"). You may find yourself coming back to this step if you find that your design doesn't fit HTTP's uniform interface. (pg 117)

There are three basic rules for URI design, born of collective experience:

1. Use path variables to encode hierarchy: parent/child
2. Put punctuation characters in path variables to avoid implying hierarchy where none exists: /parent/child1;child2
3. use query variables to imply inputs to an algorithm, for example: /search?q=jellyfish&start=20 (pg.117)

I recommend using commas when the order of the scoping information is important, and semicolons when the order doesn't' matter. (pg. 119)

The main purpose of any representation is to convey the state of the resource. ... The other job of the representation is to provide levers of state. (pg. 124)

A representation conveys the state of its resource, but it doesn't have to convey the *entire* state of the resource. (pg. 129)

I want to show that new possibilities open up when you treat everyday data structures as resources... (pg. 145)

Authentication is the problem of tying a request to a user. ... Authorization is the problem of determining which requests to let through for a given user. (pg. 146)

If you find yourself wishing there were more HTTP methods, the first thing to do is go back to step two and try to split up your data set so you have more kinds of resources. (pg. 149)

When an object's state can be represented as key-value pairs, form-encoding is the simplest representation format. (pg. 151)