HACKER Q&A
📣 maxwellg

Deduplicating resources in REST APIs List operations


Hey all:

An API Design question I'm playing around with - suppose I have two resources with a one-to-many relationship, like Authors and Books. Each Author has many Books, and for the sake of this example, each book has a single Author.

I have a REST API to search over all books according to some criteria, and return a list of books that match. I also want to include the author information for each book, to avoid callers needing to make an additional request. Two options seem reasonable at first glance:

1. Return a top-level list of authors corresponding to the books in the response, and let the caller match each author to each book. This means we aren't sending duplicate information in the response.

  GET /api/books?genre=mystery
  { 
    "metadata": { "cursor": "...", "has_next": true }
    "books": [
      { "id": 1, "name": "The Hound of the Baskervilles", "author_id": 123 },
      { "id": 1, "name": "The Man with the Twisted Lip", "author_id": 123 },
      ...
    ],
    "authors" :[
      { "id": 123, "name": "Arthur Conan Doyle" }
      ...
    ]
  }

2. Return each author as a nested field on the book object. We send duplicate information, but the response is likely easier for the caller to work with.

  GET /api/books?genre=mystery
  { 
    "metadata": { "cursor": "...", "has_next": true }
    "books": [
      { "id": 1, "name": "The Hound of the Baskervilles", "author": { "id": 123, "name": "Arthur Conan Doyle" } },
      { "id": 1, "name": "The Man with the Twisted Lip", "author": { "id": 123, "name": "Arthur Conan Doyle" } },
      ...
    ]
  }
Looking around, I've found many examples of 2, but haven't been able to find an example of 1. Are there any reasons why 1 is not more popular? Is returning bloated responses not actually a problem until you hit a certain scale?


  👤 compressedgas Accepted Answer ✓
I was going to suggest the Hypertext Application Language https://stateless.group/hal_specification.html in which such would be a list result with embedded resources for the books and authors.