Should a composition be considered a resource in REST?

Question

Consider this example system consisting of the following resources: Family, Person and Role. A Family and Person has a many-many relationship and each family member has a certain "role". For example, a family may consist of persons with the following roles: a mother, a father and two children, but the parents may themselves have the role of child in their own parents' family. Thus, the family-person-role relationship is a composition of these three resources.

My question is this: with complete disregard of system internals and data-storage structures, would this relationship be considered a resource in terms of REST or meta information associated with one of the other resources?

Answer 1

Your question is answered by considering the update operation on an object.

What we want to achieve is internal consistency of the objects. If I retrieve a Family and someone else adds a Person with the same Family id then they have broken my Family object. If I call myFamily.PersonCount() I'll get the wrong number.

There are two options,

1. Use an Aggregate Root in DDD terms. In this case the Family object is the only object you can update. All the others are child objects and hence not resources in their own rights

2. Use Foreign Keys. In this case the Family object hardly exists at all, its maybe just Id and Name. Each Person has a collection of FamilyRoles which contain a FamilyId and Role. Now if I want to get all the people in a family I call the person resource GetPersonsByFamilyId and get a collection of Persons back

Answer 2

REST is an architectural pattern and doesn't proscribe when something is a resource and when not.

As a rule of thumb, I would advise to expose something as a (sub-)resource if

1. It is identifyable as a (sub-)entity within your domain, and
2. It makes sense to retrieve and/or edit the item on its own

Answer 3

Fielding, 2000

The key abstraction of information in REST is a resource. Any information that can be named can be a resource: a document or image, a temporal service (e.g. "today's weather in Los Angeles"), a collection of other resources, a non-virtual object (e.g. a person), and so on. In other words, any concept that might be the target of an author's hypertext reference must fit within the definition of a resource.

So a relationship clearly can be a resource.

Should it be? I think that largely comes down to whether or not you can do anything useful with an independently cacheable representation of the relationship.

In many cases, questions about resources are equivalent to questions about documents -- is it useful to have a document that describes this relationship between a Person, Family, and Role? If it is, then yes by all means have a corresponding resource.