What are nested resources and where do they come from?

Question

for my thesis I need a precise definition of sub-resources (or nested resources). I read Fieldings Disseration and he indeed introduced the terms resource and resource identifier but he did not introduce the term sub-resource.

This is an example of sub-resources but why actually?

/posts/:postId/comments/:commentId

Well, an arbitraty post instance can have a set of comments but should this post instance be represented by a path parameter to be a sub-resource or could it be also hard coded?

Let's say I have a URI like

/account/status

The status belongs to the account. Is it a sub-resource?

Thanks in advance

Amit

Answer 1

A sub-resource is anything you call which contains a nested structure on it, for example if you have a post object which contains nested comment objects you can tell that a comment is a sub-resource of a post, think of it as a hierarchy of resources (objects) whose can contain objects within.

post = {   #main resource at /post/:post
 "post_id": "001",
 "comments": { #sub-resource at /post/:post/comment/:comment
       "comment_id": "001"
        },
 ...
}

Now having clarified that, is all up to you to setup the resource hierarchy inside your application so you could end up with lots of sub-resources or none at all.

Answer 2

There is no concept of a sub-resource in REST. Every resource stands on its own, and uri's should be opaque/irrelevant except for purposes of aesthetics and documentation. You should be able to change the location of a resource to a different name, or even a different server and it shouldn't affect the relationship.

The relationship between resources is not defined by their uris, it's defined by the links between them (called Hypermedia relationship in the dissertation).

How that link looks like depends on the format. In HTML it could look like:

<a href="/child" rel="item">...</a>
<a href="/parent" rel="collection">...</a>

Encoded as a HTTP link:

Link: rel="item"; </child>

Encoded as HAL:

{
  _links: {
     item: { href: '/child'}
  }
}

Answer 3

Resources having "subordinates" is an old HTTP/1.0 idea, see RFC 1945.

The POST method is used to request that the destination server accept the entity enclosed in the request as a new subordinate of the resource identified by the Request-URI in the Request-Line.

The posted entity is subordinate to that URI in the same way that a file is subordinate to a directory containing it, a news article is subordinate to a newsgroup to which it is posted, or a record is subordinate to a database.

You'll find that language was carried forward into HTTP/1.1 (RFC 2616), but was abandoned in the most recent specification (see RFC 7231).

---

If you are looking for "authoritative" definitions of "sub-resources" or "nested resources", then you'll want to be looking into identifier spelling conventions designed to support general purpose routing of requests. For instance, JaxRS, or Rails

It's common to have resources that are logically children of other resources.... Nested routes allow you to capture this relationship in your routing.

These are purely implementation details, in that they live behind the HTTP facade presented by the origin server. General purpose clients have no knowledge of these design constraints, and therefore accrue no benefit from them. For example, if you look at the current HTTP caching specification, you'll notice that invalidating a resource has no effect at all on any "sub resources" that may also be in the cache.

But choosing a URI design that aligns the mechanical hierarchical part with the logical resource hierarchy means that you can treat your resources like an object graph, which in some conditions will ease the maintenance burden.

---

Just because the whole mess isn't confusing enough, we also have the idea of secondary resources

The fragment identifier component of a URI allows indirect identification of a secondary resource by reference to a primary resource and additional identifying information.

The key idea here is that the representation of the secondary resource is enclosed with the representation of the primary resource. Think "an HTML form inside a web page".