[...] Why REST Matters (tags: REST http soap webservice) [...]

Jim, thanks for your question–it’s a good one. I think a lot of the REST/CRUD analogy has been overplayed and leads to a lot of confusion.

A resource in REST does not necessarily equate to an object in the back-end. While technologies like Rails and ActiveResource use this as the default I think it misses an important point. Resources are important nouns that are available externally. Our internal object-model is a way of breaking down the domain from the inside and has a different set of constraints applied.

Let’s take your Person example. It may very well be that Person resources need to be exposed in a singular form, but that doesn’t have to be the only form. If things like families or friends are important, they’re resources! Those resources can expose a representation of that describes the collection structure and as much per-object depth as required. In this case the collection “views” could be though of a synthesized (or calculated) datasets, but externally a single Person or a collection are all resources.

One of the hardest things I’ve found about understanding REST is to use different constraints to shape the resource taxonomy. I think a slavish adherence to a model where resources are simply exposed internal objects is the wrong choice. What resources are exposed should be shaped by the needs of your clients. A fine-grained service that requires too much traversal simply fails the needs of your clients.

Cheers,

Alex

My point was that if you had things like a person, their family and their friends you would expose them as things like, /people/fred, /people/fred/family, /people/fred/friends. If the friends and family resource are too specific, you may simply expose fred’s relations as /people/fred/relations in a suitable representation.

Hi Jim, let me see if I can provide some elaboration.

If you need fine-grained control over relations you have two choices, either expose each relationship as its own URI that can be managed with the usual HTTP verbs or simply allow clients to POST new representations of fred’s relationships. I think you have to really get a grip on what clients of your service/site really want to do with this data. I think it’s entirely acceptable to give clients a relatively generic URI (like /people/fred/contacts) and express the relations within the representation that is returned. If your clients really need specific, well-known subordinate nodes like ’spouse’ or ‘children’ then your representation will have to deal with the domain-level problems like multiple marriages and the like.

You are correct that exposing lots of fine-grained objects is a performance drain. I would add that I think it’s an unfair burden for clients of your service/site to have to deal with all of these atomic pieces. A 1-to-1 mapping of domain model to REST resources is a pretty naive approach to resource design.

Cheers,

Alex

Thanks for hanging in on this thread Jim, it’s a good discussion. I want to address your specific questions about the Person example, but before I do I want to make the assertion that REST is not object modeling. REST is an architectural style for exposing data and services. I bring this up because, while I think it’s a small example to work with, the Person example we’ve been riffing on strikes me as mapping an object model to a resource model–not necessarily something I would want to expose.

Nevertheless, it’s a decent foil for our discussion. Let me address your specific question about Fred and his friends and children. Let’s assume that the service being exposed is for Fred to declare who his friends and children (a Linked In knock-off perhaps?), and we’re highlighting “friends” and “children” as important aspects of Fred. We’ll say that Fred can modify his relations (let’s ignore authorization and authentication) and that anyone can find out who Fred’s friends and children are by issuing GET requests to /people/fred/friends and /people/fred/children, respectively.

Today Fred decides he’s ready to post a list of who his friends are. The easiest thing for the service designer to do is to enforce application-level validation that says that the representation Fred POSTs to /people/fred/friends has to be list of already-known URLs mapping to each related person.

This is nice for the service designer, but not so fun for Fred. Fred now has to keep track of which of his friends are already known to our service and which ones aren’t. One could apply some application-level heuristics to the POSTed representation that would find or create Person records for each relation prior to storing the actual relation. Whether or not we want to support that is driven entirely by what we want to support and is not constrained by REST. Resources are about pretty high-level, coarse-grained nouns. The constraint of the limited list of verbs we can apply to resources fundamentally shapes what boxes we draw around our resources. That’s okay, I think this is a good thing. Also note that some of what we’re talking about is really an application-level concern, meaning that the semantics are applied to the representations passed back and forth and aren’t strictly expressed in the declaration of resources.

Moving on, as for getting a representation of Fred’s children, I’m assuming that all people are equal in this domain and that looking at Fred as a person and one of his children as a person are of equal value. If that’s true then, yes, the GET of /people/fred/children would return a representation that should contain URLs indicating the canonical location of each child record. However that doesn’t mean that we are limited in what else we can return in that representation. There’s no need to speak exclusively in just URLs and force clients to perform additional lookup queries for each person. We can easily return immediately useful data like name, age, height, a description, etc. Again resources really describe the boxes we draw around resources, not necessarily what’s in them.

At the end of the day I think the key is thinking about the nouns you want to expose to the world. In some cases these might map to your domain model, but in a lot of cases they won’t. Some resources may be views or calculations done on your domain. Second, the representations that are sent back and forth provide a lot of flexibility for the top-level domain logic. Some things such as the nuances of how other resources and entities are referred to are best left to the application level and not a concern of REST necessarily.

I hope that provides some clarification.