I'm building a rest API that has an endpoint for a collection of items. The response is a large JSON array, which takes a while for the client to process. On the server-side, each item in the collection can be independently modified, with an associated modification timestamp.

Instead of fetching the entire collection every time, I'd like to enable the client to be able to specify a timestamp, and get a HTTP 206 Partial Content response, just with the items that have been modified since that timestamp.

I was hoping there might be a standard HTTP header to handle this scenario. I've investigated:

• Range (which seems to be only for byte ranges)
• If-Modified-Since (which seems to only control access to the whole resource)

Is there a standard set of HTTP headers to use in requests and responses that deal with diffs, or should I just invent my own?

I'm building a rest API that has an endpoint for a collection of items. The response is a large JSON array, which takes a while for the client to process. On the server-side, each item in the collection can be independently modified, with an associated modification timestamp.

Instead of fetching the entire collection every time, I'd like to enable the client to be able to specify a timestamp, and get a HTTP 206 Partial Content response, just with the items that have been modified since that timestamp.

I was hoping there might be a standard HTTP header to handle this scenario. I've investigated:

• Range (which seems to be only for byte ranges)
• If-Modified-Since (which seems to only control access to the whole resource)

Is there a standard set of HTTP headers to use in requests and responses that deal with diffs, or should I just invent my own?

• rest
• http-headers
• diff

• Don't do this with headers. It should be in the API parameters. – Barmar Commented Mar 25 at 20:12

1 Answer 1

There is an extension to HTTP that appears to solve this problem:

https://datatracker.ietf./doc/html/rfc3229

This is quite old. So am I, and I've never seen it used in the wild. Would love to see it in action though!

206 and If-Modified-Since are definitely the wrong tools for the job. Personally I would implement this using a ?since= query parameter.

You could also look at https://www.rfc-editor./rfc/rfc6578.html for inspiration, but this is a WebDAV-specific extension.