Thoughts on REST/HATEOAS Collections and the Range Header

Recently I’ve been building a lot of APIs (using the WebApi framework) and have been focusing on REST (that is proper REST with HATEOAS and other things); however I’ve been trying to come to terms in how to best represent collections, or more specifically paged collections.

I’ve been using the O’Reilly RESTful Web Services cookbook kindle edition as a reference on building REST Apis and in section 3.7 How to Design Representations of Collection (p59-60) it gives a solution to represent collections which includes links to the previous/next page and a total attribute along with the actual data. To me this doesn’t feel right; perhaps it’s because of the skip/take in the query parameter or maybe the returning data isn’t exactly a collection but a page of a collection (I’m probably been way to pedantic here). This way maybe fine for some people and still considered RESTful but I’d like to explore alternatives first.

Range Header

This stackoverflow question lead me to the use of the Range Header using a custom range unit (items seems to be quite a common example) which returns a Http Status code of 206 (Partial Content) and a Content-Range Header that includes the total number of items.

Do a count

This approach seems to be more RESTful than the book example and takes advantage of what Http specification  has to offer. I can send a HEAD request with the Range header of “items 0-0” and get back just the Content-Range; in other words I can do a count and then determine the best paging size to apply (if I need to at all). Something that the previous solution doesn’t cater for.

Leave a Reply