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.

### See Also

`gh_whoami()` for details on GitHub API token management.

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

[Package gh version 1.0.1 Index]