R: Query the GitHub API

gh {gh}

R Documentation

Query the GitHub API

Description

This is an extremely minimal client. You need to know the API to be able to use this client. All this function does is:

Try to substitute each listed parameter into endpoint, using the {parameter} notation.
If a GET request (the default), then add all other listed parameters as query parameters.
If not a GET request, then send the other parameters in the request body, as JSON.
Convert the response to an R list using jsonlite::fromJSON().

Usage

gh(
  endpoint,
  ...,
  per_page = NULL,
  .per_page = NULL,
  .token = NULL,
  .destfile = NULL,
  .overwrite = FALSE,
  .api_url = NULL,
  .method = "GET",
  .limit = NULL,
  .accept = "application/vnd.github.v3+json",
  .send_headers = NULL,
  .progress = TRUE,
  .params = list(),
  .max_wait = 600,
  .max_rate = NULL
)

Arguments

`endpoint`	GitHub API endpoint. Must be one of the following forms: `⁠METHOD path⁠`, e.g. `GET /rate_limit`, `path`, e.g. `⁠/rate_limit⁠`, `⁠METHOD url⁠`, e.g. `⁠GET https://api.github.com/rate_limit⁠`, `url`, e.g. `⁠https://api.github.com/rate_limit⁠`. If the method is not supplied, will use `.method`, which defaults to `"GET"`.
`...`	Name-value pairs giving API parameters. Will be matched into `endpoint` placeholders, sent as query parameters in GET requests, and as a JSON body of POST requests. If there is only one unnamed parameter, and it is a raw vector, then it will not be JSON encoded, but sent as raw data, as is. This can be used for example to add assets to releases. Named `NULL` values are silently dropped. For GET requests, named `NA` values trigger an error. For other methods, named `NA` values are included in the body of the request, as JSON `null`.
`per_page`, `.per_page`	Number of items to return per page. If omitted, will be substituted by `max(.limit, 100)` if `.limit` is set, otherwise determined by the API (never greater than 100).
`.token`	Authentication token. Defaults to `GITHUB_PAT` or `GITHUB_TOKEN` environment variables, in this order if any is set. See `gh_token()` if you need more flexibility, e.g. different tokens for different GitHub Enterprise deployments.
`.destfile`	Path to write response to disk. If `NULL` (default), response will be processed and returned as an object. If path is given, response will be written to disk in the form sent. gh writes the response to a temporary file, and renames that file to `.destfile` after the request was successful. The name of the temporary file is created by adding a `⁠-<random>.gh-tmp⁠` suffix to it, where `⁠<random>⁠` is an ASCII string with random characters. gh removes the temporary file on error.
`.overwrite`	If `.destfile` is provided, whether to overwrite an existing file. Defaults to `FALSE`. If an error happens the original file is kept.
`.api_url`	Github API url (default: https://api.github.com). Used if `endpoint` just contains a path. Defaults to `GITHUB_API_URL` environment variable if set.
`.method`	HTTP method to use if not explicitly supplied in the `endpoint`.
`.limit`	Number of records to return. This can be used instead of manual pagination. By default it is `NULL`, which means that the defaults of the GitHub API are used. You can set it to a number to request more (or less) records, and also to `Inf` to request all records. Note, that if you request many records, then multiple GitHub API calls are used to get them, and this can take a potentially long time.
`.accept`	The value of the `Accept` HTTP header. Defaults to `"application/vnd.github.v3+json"` . If `Accept` is given in `.send_headers`, then that will be used. This parameter can be used to provide a custom media type, in order to access a preview feature of the API.
`.send_headers`	Named character vector of header field values (except `Authorization`, which is handled via `.token`). This can be used to override or augment the default `User-Agent` header: `"https://github.com/r-lib/gh"`.
`.progress`	Whether to show a progress indicator for calls that need more than one HTTP request.
`.params`	Additional list of parameters to append to `...`. It is easier to use this than `...` if you have your parameters in a list already.
`.max_wait`	Maximum number of seconds to wait if rate limited. Defaults to 10 minutes.
`.max_rate`	Maximum request rate in requests per second. Set this to automatically throttle requests.

Value

Answer from the API as a gh_response object, which is also a list. Failed requests will generate an R error. Requests that generate a raw response will return a raw vector.

Examples


## Repositories of a user, these are equivalent
gh("/users/hadley/repos", .limit = 2)
gh("/users/{username}/repos", username = "hadley", .limit = 2)

## Starred repositories of a user
gh("/users/hadley/starred", .limit = 2)
gh("/users/{username}/starred", username = "hadley", .limit = 2)


## Create a repository, needs a token in GITHUB_PAT (or GITHUB_TOKEN)
## environment variable
gh("POST /user/repos", name = "foobar")


## Issues of a repository
gh("/repos/hadley/dplyr/issues")
gh("/repos/{owner}/{repo}/issues", owner = "hadley", repo = "dplyr")

## Automatic pagination
users <- gh("/users", .limit = 50)
length(users)


## Access developer preview of Licenses API (in preview as of 2015-09-24)
gh("/licenses") # used to error code 415
gh("/licenses", .accept = "application/vnd.github.drax-preview+json")


## Access Github Enterprise API
## Use GITHUB_API_URL environment variable to change the default.
gh("/user/repos", type = "public", .api_url = "https://github.foobar.edu/api/v3")


## Use I() to force body part to be sent as an array, even if length 1
## This works whether assignees has length 1 or > 1
assignees <- "gh_user"
assignees <- c("gh_user1", "gh_user2")
gh("PATCH /repos/OWNER/REPO/issues/1", assignees = I(assignees))


## There are two ways to send JSON data. One is that you supply one or
## more objects that will be converted to JSON automatically via
## jsonlite::toJSON(). In this case sometimes you need to use
## jsonlite::unbox() because fromJSON() creates lists from scalar vectors
## by default. The Content-Type header is automatically added in this
## case. For example this request turns on GitHub Pages, using this
## API: https://docs.github.com/v3/repos/pages/#enable-a-pages-site

gh::gh(
  "POST /repos/{owner}/{repo}/pages",
  owner = "r-lib",
  repo = "gh",
  source = list(
    branch = jsonlite::unbox("gh-pages"),
    path = jsonlite::unbox("/")
  ),
  .send_headers = c(Accept = "application/vnd.github.switcheroo-preview+json")
)

## The second way is to handle the JSON encoding manually, and supply it
## as a raw vector in an unnamed argument, and also a Content-Type header:

body <- '{ "source": { "branch": "gh-pages", "path": "/" } }'
gh::gh(
  "POST /repos/{owner}/{repo}/pages",
  owner = "r-lib",
  repo = "gh",
  charToRaw(body),
  .send_headers = c(
    Accept = "application/vnd.github.switcheroo-preview+json",
    "Content-Type" = "application/json"
  )
)


## Pass along a query to the search/code endpoint via the ... argument
x <- gh::gh(
            "/search/code",
            q = "installation repo:r-lib/gh",
            .send_headers = c("X-GitHub-Api-Version" = "2022-11-28")
            )
 str(x, list.len = 3, give.attr = FALSE)