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?