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:
- 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...). - Explicitly specify a fields list only if it differs from the default fields list.
- 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?