Update Best Practices doc for Github API Conditional Requests to mention limitations

[mikebroberts]

Code of Conduct

• I have read and agree to the GitHub Docs project's 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 .

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[nguyenalex836]

@mikebroberts Thank you for raising this issue! I'll get this triaged for review ✨ Our team will provide feedback regarding the best next steps for this issue - thanks for your patience! 💛

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[nguyenalex836]

@mikebroberts Thank you for your patience while our SME team reviewed! Your analysis is correct 💛 Would you be open to raising a PR to call out this behavior with Apps?

[github-actions]

This issue has been automatically closed because there has been no response to our request for more information from the original author. With only the information that is currently in the issue, we don't have enough information to take action. Please reach out if you have or find the answers we need so that we can investigate further. See this blog post on bug reports and the importance of repro steps for more information about the kind of information that may be helpful.

[JoshuaTheMiller]

I believe this Issue should remain open as I did not find this mentioned in the existing docs (linked above).

Getting this called out in the documentation in some way would likely save application authors a LOT of headache 😁 (perhaps speaking from personal experience).

[nguyenalex836]

@JoshuaTheMiller Thanks for the nudge on this! ✨ I've just reopened - would you be willing to raise a PR calling out this behavior with Apps? If not, we can look at opening this up to the community 💛

[github-actions]

This issue has been automatically closed because there has been no response to our request for more information from the original author. With only the information that is currently in the issue, we don't have enough information to take action. Please reach out if you have or find the answers we need so that we can investigate further. See this blog post on bug reports and the importance of repro steps for more information about the kind of information that may be helpful.