How to correctly use ETag with the paginated responses in REST API

Hello all,

I’m trying to implement ETag usage, but I was unable to find information on how to correctly use ETag for paginated responses. For example, I send the following request (assuming that the answer has more than 20 entries):

GET user/repos?per_page=20

GitHub response 1 is:

ETag: W/"abcdef"
Link: xxxx

From the ‘Link’ field I get a request for the next page and send it:

GET user/repos?per_page=20&page=2

GitHub response 2 is:

ETag: W/"123456"
Link: xxxx

… and so on.

Now I want to use ETag to get the data again, and send the following request:

GET user/repos?per_page=20
If-None-Match: "abcdef"

The GitHub response is:

HTTP 304 Not Modified

My question is – how I should interpret the GitHub answer:

  1. Only the first page has not been modified, and I should make calls for other pages too (with their ETags)? But there is no ‘Link’ header in the response…
  2. The entire data array has not been modified including all subsequent pages, so no additional requests are required?

Thank you.

Hi @denis-bigbrassband-com :wave:

Thanks for the question. The ETag is returned per page and is only applicable to the resources in that page (so your interpretation 1).

In general, I would recommend conditional requests with large page sizes, and webhooks when possible.

Read more here:

Hi John,

Thank you for the confirmation.
Yes, we use the maximum possible page size – 100 (as mentioned here).
But for large lists (yes, we have such ones) it anyway gives 10-100 requests, and I had a hope that this may be reduced to just 1 in case if nothing is changed in the requested data.

Also, it seems that we have to cache the next page link too, as it is absent in the 304 response.

Thank you again for the clarification, it really helped us to implement this feature correctly.