REST API endpoint returning detailed or summary data

api-designrest

I'm designing a REST API that returns a collection of elements that can contain some verbose metadata, similar to one that might return books from a library.

Is there a REST API design pattern to offer two different responses to a /books GET query, one which returns a full listing of books and metadata (title, author, publisher, page count, etc.), and one that just returns summary information (title and author)? I've considered using a query parameter, like "?summary", and this implementation is not difficult.

Then the other side of this is, using "?summary", I get a very different JSON structure than without.

Is a query parameter a good approach? And how do I reconcile this requirement with returning a consistent response for all queries to this endpoint? (I don't want to use separate /books and /books_summary endpoints.)

Best Answer

I've seen two main patterns:

  • Having something like a fields parameter that lets the user query for exactly the fields they want, providing a default set if not specified.
  • Returning summary data in a list endpoint, but detailed data in individual resource endpoints. e.g. /books contains summary data, but /book/1 contains detailed data.

Your summary idea is not terrible. Could also call it verbose. The main drawback I see is that different people have different ideas of what belongs in a summary, so if you're not careful, you might end up with that creeping larger over time.

Related Topic