How to return only the changed resources in a collection using REST

Question

Let's say I'm designing a REST API that should return a list of an authenticated user's contacts

e.g. /users/me/contacts

To improve performance I'll return an ETag and provide this in future GET requests in the If-None-Match header. Assuming nothing has changed then the API will return a Not-Modified response.

However what happens when the list of contacts has changed? I don't want to return the entire collection again, just the new and modified items.

I could send a HEAD request, compare ETags and then send a subsequent GET request for the new items but this seems a bit wasteful.

I've just come across the If-Range header which looks like it might solve the issue but it seems to also require the Range header which is specified in bytes.

Do you think the If-Range header is the way to go or am I missing something obvious?

Answer 1

REST is about resources. If /users/me/contacts is the URL of a resource (list of contacts), it must always return the full representation of the resource state.

If you want to retrieve only those contacts that have changed, use a query parameter:

/users/me/contacts?newerThan=20130513124300

with newerThan the date the client last accessed the resource.

This would be RESTful since every different value of newerThan would form a different URL.