R: GitHub API

gh {gh}

R Documentation

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.

Examples

## 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))

## End(Not run)