search

github / docs

The open-source repo for docs.github.com
https://docs.github.com
Creative Commons Attribution 4.0 International
16.15k stars 59.37k forks source link

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

Open mikebroberts opened 6 days ago

mikebroberts commented 6 days ago

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[bot] commented 6 days ago

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 commented 5 days ago

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

github-actions[bot] commented 4 days ago

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