GitHub REST API client for Node.js
Install with npm install @octokit/rest
.
const octokit = require('@octokit/rest')()
// Compare: https://developer.github.com/v3/repos/#list-organization-repositories
octokit.repos.getForOrg({
org: 'octokit',
type: 'public'
}).then(({data}) => {
// handle data
})
All available client options with default values
const octokit = require('@octokit/rest')({
timeout: 0, // 0 means no request timeout
requestMedia: 'application/vnd.github.v3+json',
headers: {
'user-agent': 'octokit/rest.js v1.2.3' // v1.2.3 will be current version
},
// change for custom GitHub Enterprise URL
host: 'api.github.com',
pathPrefix: '',
protocol: 'https',
port: 433,
// advanced request options
// see https://nodejs.org/api/http.html
proxy: undefined,
ca: undefined,
rejectUnauthorized: undefined,
family: undefined
})
@octokit/rest
API docs: https://octokit.github.io/rest.js/
GitHub v3 REST API docs: https://developer.github.com/v3/
Most GitHub API calls don't require authentication. Rules of thumb:
- If you can see the information by visiting the site without being logged in, you don't have to be authenticated to retrieve the same information through the API.
- If you want to change data, you have to be authenticated.
// basic
octokit.authenticate({
type: 'basic',
username: 'yourusername',
password: 'password'
})
// oauth
octokit.authenticate({
type: 'oauth',
token: 'secrettoken123'
})
// oauth key/secret (to get a token)
octokit.authenticate({
type: 'oauth',
key: 'client_id',
secret: 'client_secret'
})
// token (https://github.com/settings/tokens)
octokit.authenticate({
type: 'token',
token: 'secrettoken123'
})
// GitHub app
octokit.authenticate({
type: 'integration',
token: 'secrettoken123'
})
Note: authenticate
is synchronous because it only sets the credentials
for the following requests.
There are a few pagination-related methods:
hasNextPage(response)
hasPreviousPage(response)
hasFirstPage(response)
hasLastPage(response)
getNextPage(response)
getPreviousPage(response)
getFirstPage(response)
getLastPage(response)
Usage
async function paginate (method) {
let response = await method({per_page: 100})
let {data} = response
while (octokit.hasNextPage(response)) {
response = await octokit.getNextPage(response)
data = data.concat(response.data)
}
return data
}
paginate(octokit.repos.getAll)
.then(data => {
// handle all results
})
Set DEBUG=octokit:rest*
for additional debug logs.
Run all tests
$ npm test
Or run a specific test
$ ./node_modules/.bin/mocha test/test/integration/get-repository-test.js
The examples are run as part of the tests. You can set an EXAMPLES_GITHUB_TOKEN
environment
variable (or set it in a .env
file) to avoid running against GitHub's rate limit.
We would love you to contribute to @octokit/rest
, pull requests are very welcomed!
Please see CONTRIBUTING.md for more information.
@octokit/rest
was originally created as node-github
in 2012 by Mike de Boer from Cloud9 IDE, Inc.
It was adopted and renamed by GitHub in 2017