restapi-designlevel-of-detail

Good method for a REST API client to specify the desired amount of detail of the response?


I am designing a REST API that will be used by several clients to query a data repository. I am anticipating that these clients will have different needs regarding the amount/level of detail of the responses.

Let's say I can query a collection of books. A book might potentially have lots of attributes (more than any single client might be interested in), maybe even subresources, and a client might request a large number of books, leading to a response body that is larger than required.

Therefore I am looking into ways of optimizing response size. The idea is to give the API client some means of specifying how much detail should be included in the response.

I would be interested to learn how this problem has been solved before; which mechanism worked well in practice and which didn't, which API design is particularly RESTful and which isn't, and so on.

A few ways I can think of how a client could possibly specify desired level of detail for the response:

There are possibly more strategies for selecting the desired level of detail. I am interested to learn what works well in practice, without compromising RESTfulness too badly.


Solution

  • I think it depends mostly on how much flexibility you want to give to your API clients.

    If you know the different uses of your data, you might want to define some available formats that your API can return.

    For example, using this structure:

     GET /books (with a default format if nothing is specified)
     GET /books/minimal 
     GET /books/full 
     GET /books/otherformat
    

    Note that this could also be using this URL structure if you don't want to duplicate your endpoints:

    GET /books?format=minimal
    

    However, in either case, this forces you to know exactly what data your clients will need or want at any given time.

    I would not rely on media types as this might be more confusing for users than other more standard way of working with REST APIs.

    [EDIT]

    Also, should you decide to specify the whole list of fiends to return and find out that GET requests are not sufficient, you could refer to this post for an alternate way using POST requests