REST(Representational State Transfer) is one of the most important and pervasive ideas in modern web application development. It is also one of the most difficult to understand, because there is a lot of FUD out there, and the source material is written in academic language that can be difficult to comprehend. I got a good question from a ex-colleague the other day, and I though it would be good to share my response here.
Question:
I am interested in how DB relationships are expressed over a RESTful web api. Sometimes people include relationships in the json response for entities - i.e. a product could have an array of images, or of related products. However, I’m not sure if this is appropriate. What are the best practises for expressing these types of relationships?
Answer:
tl;dr: Universality is the key: while it is certainly convenient in many cases to include an embedded resource as part of the representation of your resource, the point of REST is to provide a universal interface to resources for all components (for our purposes, view and web service). As such, the representation your view uses to create or update a resource should be the same as the representation your service responds with when querying.
There is one and only one definitive resource on the subject Chapter 5 of Roy Fielding’s 2000 dissertation.
In the language of REST, you aren’t talking about DB relationships, you’re talking about resource relationships. This distinction may seem pedantic, but as we’ll see it’s important.
Section 5.2 is where Fielding really gets into the meat of the issue.
REST components communicate by transferring a representation of a resource in a format matching one of an evolving set of standard data types, selected dynamically based on the capabilities or desires of the recipient and the nature of the resource. Whether the representation is in the same format as the raw source, or is derived from the source, remains hidden behind the interface.
For our purposes a component refers to either a frontend application (hereafter a view), or a web service application. What this means is that your web service can store data in whatever data-architecture is most convenient for the application, but should expose representations of the resource that are useful and meaningful for communicating with a view. This is why I took the time to recognize the difference between a DB relationship and resource relationship. While your REST api may represent a relationship between resources, the service need not represent it internally in the same format.
Okay, but what about relationships between resources, should they be included in my representation? Fielding goes on to describe representations of resources later in Section 5.2.1.2:
REST components perform actions on a resource by using a representation to capture the current or intended state of that resource and transferring that representation between components. A representation is a sequence of bytes, plus representation metadata to describe those bytes. Other commonly used but less precise names for a representation include: document, file, and HTTP message entity, instance, or variant.
So, the details of the representation of a resources is up to you, REST doesn’t specify. Now, Fielding doesn’t talk specificaly about resource relationships, but logic implies that part of that representation could easily be information about this resource’s relationships to other resources. The most common example of such information is a URI specifier to the embedded resource.
An example
# GET /product/1
{
"id": 1,
"uri": "/product/1",
"name": "Monster Truck",
# Here, a URI represents another resource
"productGroup": "/product_group/1",
...
}
# GET /product_group/1
{
"id": 1,
"uri": "/product_group/1",
"name": "Trucks",
"description": "Toy trucks are great for kids",
# More URI's representing other resources.
"products": ["/product/1", ...],
...
}
In order to render a product, I also need to have access to the productGroup to which it belongs, because the view includes the product group’s description. But that means to render a product, I must round trip to the server (at least) twice! Surely that can’t be performant! Fielding knew the too, and to respond to this criticism, REST is designed to be a very cache-friendly architecture. After the first request for a productGroup there will be a ready cache, and over time fetching the productGroup should be amortized-fast.
We have seen how you can avoid embedding a relationship, but surely if we are able to include metadata about relationships, why should we bother with a cache at all, and not just embed the related resource in the representation. You might be saying “No matter how good my cache is, it’ll always be slower to have to make mulitple requests!”
Isn’t this just as RESTful?
# GET /product/1
{
"id": 1,
"uri": "/product/1",
"name": "Monster Truck",
# My representation includes all the productGroup metadata my view needs.
"productGroup": {
"id": 1,
"uri": "/product_group/1",
"name": "Trucks",
"description": "Toy trucks are great for kids",
...
}
...
}
Unfortunately, no. Consider Section 5.1.5:
The central feature that distinguishes the REST architectural style from other network-based styles is its emphasis on a uniform interface between components (Figure 5-6). By applying the software engineering principle of generality to the component interface, the overall system architecture is simplified and the visibility of interactions is improved.
This means that if you create a resource (in HTTP this is usually a POST where the body is the representation of the resource), if you request that same resource (a GET where the response body is the representation), you should expect the same representation from the server. It is obvious when we consider it in this light, that the above representation wouldn’t be a suitable representation for creating a product. However, if we consider our earlier example, we see that this is indeed a reflexive representation, suited to the uniform nature of rest interfaces.
A truly RESTful API is an uniform interface between the components. We trade off additional round trips for overall system architecture simplification.