gh: Query the GitHub API

In gh: 'GitHub' 'API'

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.

See Also

gh_gql() if you want to use the GitHub GraphQL API, gh_whoami() for details on GitHub API token management.

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)

gh documentation built on May 29, 2024, 4:48 a.m.