gh (version 1.0.1)

gh: GitHub API

Description

Minimal wrapper to access GitHub's API.

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, ..., .token = NULL, .api_url = NULL, .method = "GET",
  .limit = NULL, .send_headers = 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 url placeholders, sent as query parameters in GET requests, and in the JSON body of POST requests.

.token

Authentication token.

.api_url

Github API url (default: https://api.github.com). Used if endpoint just contains a path.

.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.

.send_headers

Named character vector of header field values (excepting Authorization, which is handled via .token). This can be used to override or augment the defaults, which are as follows: the Accept field defaults to "application/vnd.github.v3+json" and the User-Agent field defaults to "https://github.com/r-lib/gh". This can be used to, e.g., provide a custom media type, in order to access a preview feature of the API.

Value

Answer from the API as a gh_response object, which is also a list. Failed requests will generate an R error.

See Also

gh_whoami() for details on GitHub API token management.

Examples

Run this code
# NOT RUN {
## Repositories of a user, these are equivalent
gh("/users/hadley/repos")
gh("/users/:username/repos", username = "hadley")

## Starred repositories of a user
gh("/users/hadley/starred")
gh("/users/:username/starred", username = "hadley")

## 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") # error code 415
gh("/licenses",
   .send_headers = c("Accept" = "application/vnd.github.drax-preview+json"))

## Access Github Enterprise API
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))
# }
# NOT RUN {
# }

Run the code above in your browser using DataLab