RESTful way to ask for subset of a resource

Question

Suppose I have a resource called user_stats, that has things like how many posts, comments, likes, and followers users have. Is there a RESTful way to only ask for parts of that statistics (i.e. for user_stats/3, tell me how many posts and comments this user has, but don't tell me how many follower this user has.)

The reason I'm asking is some statistical attributes can be computationally intensive (yes I'm generating them at query time). So simply not asking for it can reduce workload.

Answer 1

There is a very useful 38 page free ebook with best practices about designing Web APIs, you might find it helpful, at least I did.

For your case, it is stated:

Add optional fields in a comma-delimited list

The Google approach works extremely well.

Here's how to get just the information we need from our dogs API using this approach:

/dogs?fields=name,color,location

It's simple to read; a developer can select just the information an app needs at a given time; it cuts down on bandwidth issues, which is important for mobile apps. The partial selection syntax can also be used to include associated resources cutting down on the number of requests needed to get the required information.

Maybe that's what you re looking for?

Answer 2

there are at least three options:

1. Use query parameter as a filter

   e.g. user_stats?fields=posts,comments

2. Make user_stats composite resource and create new resources for particular stat

   e.g. /user_stats in JSON

   {
     "blogs" : {
         "count" : 10,
         "link" : "/user_stats_blobs"
      },
      ...
   } 
   

   then you can get whole stats (GET /user_stats) or just a piece (GET /user_stats_blobs)

3. Create filter representation; use POST to post filter representation as part of request

   e.g. Request POST /user_stats/filter

    {
        "fields" : [ "blogs", ...]
    }
   

   response body contains just requested/filtered data.

All solutions are RESTful. Solution 1. is easy to implement but has limited extensibility and transparency. Solution 2. expects that you create new resources which is overhead in this case (you need just one number). so, I would recommend solution 3. because is no so hard to implement, is easily extensible and transparent.