Update Best Practices doc for Github API Conditional Requests to mention limitations #34689
Labels
content
This issue or pull request belongs to the Docs Content team
more-information-needed
More information is needed to complete review
rest
Content related to rest - overview.
SME reviewed
An SME has reviewed this issue/PR
Code of Conduct
What article on docs.github.com is affected?
https://docs.github.com/en/rest/using-the-rest-api/best-practices-for-using-the-rest-api?apiVersion=2022-11-28#use-conditional-requests-if-appropriate
What part(s) of the article would you like to see updated?
The section in this doc "Use conditional requests if appropriate" explains how to use conditional requests to avoid rate limit concerns for repeated use. However there's a problem with this approach which isn't mentioned in the doc - this solution only works when the access token being used to make the REST API doesn't change. When a different access token is used a different etag is returned, and further setting the
if-none-match
header for an etag value given with a previous token doesn't give the 304 response.This is particularly a problem when using a GitHub App since the "installation token" refreshes (at least) every hour. Therefore this "best practice" will not be appropriate in many scenarios when using a GitHub App.
I suspect changing the API behavior will be hard or may never happen, so I think it's worth at least updating the document. I had made an assumption that conditional requests would work during the design of a GitHub App - based on this doc - and now that I know that they don't I have to rethink a few things.
Additional information
The overall issue with the API was raised in 2023 here by someone else - https://github.com/orgs/community/discussions/75228#discussioncomment-10697940 .
The text was updated successfully, but these errors were encountered: