diff --git a/README.md b/README.md index d922918263c..378e801f394 100644 --- a/README.md +++ b/README.md @@ -257,22 +257,28 @@ if _, ok := err.(*github.AcceptedError); ok { ### Conditional Requests ### -The GitHub API has good support for conditional requests which will help -prevent you from burning through your rate limit, as well as help speed up your -application. `go-github` does not handle conditional requests directly, but is -instead designed to work with a caching `http.Transport`. We recommend using -[gregjones/httpcache](https://github.com/gregjones/httpcache) for that. For example: +The GitHub REST API has good support for [conditional HTTP requests](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) +via the `ETag` header which will help prevent you from burning through your +rate limit, as well as help speed up your application. `go-github` does not +handle conditional requests directly, but is instead designed to work with a +caching `http.Transport`. + +Typically, an [RFC 7234](https://datatracker.ietf.org/doc/html/rfc7234) +compliant HTTP cache such as [gregjones/httpcache](https://github.com/gregjones/httpcache) +is recommended, ex: ```go import "github.com/gregjones/httpcache" - client := github.NewClient( - httpcache.NewMemoryCacheTransport().Client() - ).WithAuthToken(os.Getenv("GITHUB_TOKEN")) +client := github.NewClient( + httpcache.NewMemoryCacheTransport().Client() +).WithAuthToken(os.Getenv("GITHUB_TOKEN")) ``` -Learn more about GitHub conditional requests in -["Use conditional requests if appropriate"](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). +Alternatively, the [bored-engineer/github-conditional-http-transport](https://github.com/bored-engineer/github-conditional-http-transport) +package relies on (undocumented) GitHub specific cache logic and is +recommended when making requests using short-lived credentials such as a +[GitHub App installation token](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-as-a-github-app-installation). ### Creating and Updating Resources ### diff --git a/github/doc.go b/github/doc.go index 4deb94c7356..79d92d9ee07 100644 --- a/github/doc.go +++ b/github/doc.go @@ -138,11 +138,17 @@ To detect this condition of error, you can check if its type is # Conditional Requests -The GitHub API has good support for conditional requests which will help -prevent you from burning through your rate limit, as well as help speed up your -application. go-github does not handle conditional requests directly, but is -instead designed to work with a caching http.Transport. We recommend using -https://github.com/gregjones/httpcache for that. +The GitHub REST API has good support for conditional HTTP requests +via the ETag header which will help prevent you from burning through your +rate limit, as well as help speed up your application. go-github does not +handle conditional requests directly, but is instead designed to work with a +caching http.Transport. + +Typically, an RFC 7234 compliant HTTP cache such as https://github.com/gregjones/httpcache +is recommended. Alternatively, the https://github.com/bored-engineer/github-conditional-http-transport +package relies on (undocumented) GitHub specific cache logic and is +recommended when making requests using short-lived credentials such as a +GitHub App installation token. Learn more about GitHub conditional requests at https://docs.github.com/rest/overview/resources-in-the-rest-api#conditional-requests.