Nesting & Relationships

Resources relate to each other, and the URI structure can express some of those relationships. The trick is nesting enough to be intuitive without building brittle, deeply nested paths.

Sub-resources

When one resource clearly belongs to another, nest it one level:

GET  /articles/42/comments        # comments of article 42
POST /articles/42/comments        # add a comment to article 42
GET  /users/7/articles            # articles written by user 7

flowchart LR
  A[/articles/42/] --> C[/articles/42/comments/]
  C --> CI[/articles/42/comments/9/]

One level of nesting reads naturally; deeper gets unwieldy

How deep to nest

Stop at one, occasionally two, levels. A path like /users/7/articles/42/comments/9/reactions/3 is hard to read and couples resources that should stand alone. Once a sub-resource has its own identity, give it a top-level URI too and link to it instead of nesting further:

GET /comments/9          # the comment as a first-class resource
GET /articles/42/comments # still fine as a scoped collection

Linking

Rather than embedding everything, return references the client can follow:

JavaScript

function articleResponse(article) {
  return {
    id: article.id,
    title: article.title,
    author: { id: article.authorId, href: '/users/' + article.authorId },
    comments: { href: '/articles/' + article.id + '/comments' },
  };
}

console.log(JSON.stringify(articleResponse({ id: 42, title: 'Hi', authorId: 7 }), null, 2));