Way to specify resource's fields list in RESTful API request

rest restapi
Ivan Velichko picture Ivan Velichko · Aug 14, 2013 · Viewed 35.1k times · Source

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?

Answer

Dan Rowlands picture Dan Rowlands · Aug 14, 2013

I'd go for option 2 IMHO.

So 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

Edit: Looking back at this I’d change the request to be:

/posts/42?fields=subject,author_name

/post/42 is the resource, not fields.

Related questions

What is a good way to transfer binary data to a HTTP REST API service?

We are extending our HTTP REST API to allow clients to upload picture (for the purpose of this question, assuming binary data). So far we have only allowed simply strings in our API parameters. What is a good way to …

Read More
Python post request with Bearer token

Im trying to make a script that post data on REST service together with Bearer token. Here is working PHP example: $postData = array( 'app' => 'aaaa' ); $ch = curl_init($apiUrl); curl_setopt_array($ch, array( CURLOPT_HTTPHEADER, ['Authorization: Bearer '.$…

Read More
Which HTTP response code for "This email is already registered"?

I'm creating a RESTful API for creating users that enforces unique email addresses: Successful POST /users: HTTP 201 Created If I POST the same email address again, what should the response code be? Is 409 Conflict the appropriate response code?

Read More