rest

How to design a REST API to request only specific fields from a resource


I have a RESTful API within a web-service with resources such as users, posts and so on. When I make a request for a list of posts (GET /posts), I want to retrieve an array of posts only with limited data for each post (i.e. subject, author name). When I make a request for a concrete post (GET /posts/42) I want to retrieve the full list of post object fields, including big post body, additional info about likes count, comments count. I suppose there exist many ways to solve this problem.
In my mind, the three most obvious are:

  1. Explicitly specify a fields list on every request (/posts?fields=subject,author_name and /posts/42?fields=subject,body,createAt,author_name,comments_count,likes_count, etc...).
  2. Explicitly specify a fields list only if it differs from the default fields list.
  3. Specify a fields list that should be excluded (or included) from (to) the default fields set if the desired fields set differs from the default.

I want to build a clear and useful API for my customers. Which way should I choose?


Solution

  • I'd go for option 2.

    If the consumer just requests the resource URL (/posts/42) they receive the default fields.

    Then consumers can alter the default response by defining values in the query string like:

    /posts/42/fields?subject,author_name

    This has worked well for me in the past and is how some other well know APIs work, e.g. Facebook

    Although I'd change the request to be:

    /posts/42?fields=subject,author_name

    /post/42 is the resource, not fields.