RESTful API Design: can your API give developers just the information they need?
Brian Mulloy
Let's talk about pagination and partial response. How do you give developers exactly the information they need?
Partial response
Take for example the Twitter API - a request for a tweet. You'll get much more than a typical twitter app often needs - including the name of person, the text of the tweet, a timestamp, how often the message was retweeted, and a lot of metadata.
Let's look at how several leading APIs handle giving developers just what they need in responses, including Google who pioneered the idea of partial response.
/people:(id,first-name,last-name,industry)
This request on a person returns ID, first name, last name, and industry.
LinkedIn uses this terse :(...) syntax which isn't self-evident. Plus it's difficult for a developer to reverse engineer the meaning using a search engine. But this is the way that LinkedIn does partial selection.
/joe.smith/friends?fields=id,name,picture
?fields=title,media:group(media:thumbnail)
Google and Facebook have a similar approach, which works well.
They each have an optional parameter called fields after which you put the names of fields you want to be returned.
As you see in this example, you can also put sub-objects in responses to pull in other information from additional resources.
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.
Make it easy for developers to paginate objects in a database
It's almost always a bad idea to return every resource in a database.
Let's look at how Facebook, Twitter, and LinkedIn handle pagination.
- Facebook uses offset and limit
- Twitter uses page and rpp (records per page)
- LinkedIn uses start and count
Semantically, Facebook and LinkedIn do the same thing. That is, the LinkedIn start & count is used in the same way as the Facebook offset & limit.
Say you want to get records 50 through 75 from each system. You would use:
- Facebook - offset 50 and limit 25
- Twitter - page 3 and rpp 25 (records per page)
- LinkedIn - start 50 and count 25
Use limit and offset
I recommend limit and offset. It is more common, well understood in leading databases, and easy for developers.
/dogs?limit=25&offset=50
What about defaults?
My loose rule of thumb for default pagination is limit=10 with offset=0.
limit=10&offset=0
The pagination defaults are of course dependent on your data size. If your resources are large, you probably want to limit it to fewer than 10; if resources are small, it can make sense to choose a larger limit.
In summary:
Support partial response by adding optional fields in a comma delimited list
Use limit and offset to make it easy for developers to paginate objects.
