GitHub REST API client for JavaScript
- Usage
- API docs
- API Previews
- Authentication
- Custom requests
- Pagination
- Hooks
- Plugins
- Register custom endpoint methods
- Throttling
- Automatic retries
- Debug
- Contributing
- Credits
- LICENSE
Install with npm install @octokit/rest.
const octokit = require('@octokit/rest')()
// Compare: https://developer.github.com/v3/repos/#list-organization-repositories
octokit.repos.listForOrg({
org: 'octokit',
type: 'public'
}).then(({ data, headers, status }) => {
// handle data
})-
Download
octokit-rest.min.jsfrom the latest release: https://github.com/octokit/rest.js/releases -
Load it as script into your web application:
<script src="octokit-rest.min.js"></script>
-
Initialize
octokitconst octokit = new Octokit() // Compare: https://developer.github.com/v3/repos/#list-organization-repositories octokit.repos.getForOrg({ org: 'octokit', type: 'public' }).then(({data, headers, status}) => { // handle data })
All available client options with default values
const octokit = require('@octokit/rest')({
timeout: 0, // 0 means no request timeout
headers: {
accept: 'application/vnd.github.v3+json',
'user-agent': 'octokit/rest.js v1.2.3' // v1.2.3 will be current version
},
// custom GitHub Enterprise URL
baseUrl: 'https://api.github.com',
// Node only: advanced request options can be passed as http(s) agent
agent: undefined
})Find all APIs documented at https://octokit.github.io/rest.js/.
To take advantage of GitHub’s API Previews,
pass a custom accept header, which you can do with any endpoint method documented
in the API docs, e.g.
const { data: { topics } } = await octokit.repos.get({
owner: 'octokit',
repo: 'rest.js',
headers: {
accept: 'application/vnd.github.mercy-preview+json'
}
})Multiple preview headers can be combined by separating them with commas
const { data: { topics, codeOfConduct } } = await octokit.repos.get({
owner: 'octokit',
repo: 'rest.js',
headers: {
accept: 'application/vnd.github.mercy-preview+json,application/vnd.github.scarlet-witch-preview+json'
}
})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 or increase higher rate limit for server-server requests)
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: 'app',
token: 'secrettoken123'
})Note: authenticate is synchronous because it only sets the credentials
for the following requests.
To send custom requests you can use the lower-level octokit.request() method
octokit.request('GET /')The baseUrl, headers and other defaults are already set. For more information
on the octokit.request() API see @octokit/request
All the endpoint methods such as octokit.repos.get() are aliases of octokit.request()
with pre-bound default options. So you can use the @octokit/request API to
get the default options or get generic request option to use with your preferred
request library.
const defaultOptions = octokit.repos.get.endpoint.DEFAULTS
const requestOptions = octokit.repos.get.endpoint()All endpoint methods starting with .list* do not return all responses at once but instead return the first 30 items by default, see also GitHub’s REST API pagination documentation.
To automatically receive all results across all pages, you can use the octokit.paginate() method:
octokit.paginate('GET /repos/:owner/:repo/issues', { owner: 'octokit', repo: 'rest.js' })
.then(issues => {
// issues is an array of all issue objects
})octokit.paginate() accepts the same options as octokit.request(). You can optionally pass an additional function to map the results from each response. The map must return a new value, usually an array with mapped data.
octokit.paginate('GET /repos/:owner/:repo/issues', { owner: 'octokit', repo: 'rest.js' }, response => response.data.map(issue => issue.title))
.then(issueTitles => {
// issueTitles is now an array with the titles only
})To stop paginating early, you can call the done() function passed as 2nd argument to the response map function. Note that you still have to return the value you want to map the response to, otherwise the last response will be mapped to undefined.
octokit.paginate('GET /organizations', (response, done) => {
if (response.data.find(issues => issue.body.includes('something'))) {
done()
}
return response.data
})To paginate responses for one of the registered endpoint methods such as octokit.issues.listForRepo() you can use the .endpoint.merge() method registered for all endpoint methods:
const options = octokit.issues.listForRepo.endpoint.merge({ owner: 'octokit', repo: 'rest.js' })
octokit.paginate(options)
.then(issues => {
// issues is an array of all issue objects
})If your runtime environment supports async iterators (such as Node 10+), you can iterate through each response
for await (const response of octokit.paginate.iterator(options)) {
// do whatever you want with each response, break out of the loop, etc.
}octokit.paginate.iterator() accepts the same options as octokit.paginate().
You can customize Octokit’s request lifecycle with hooks. Available methods are
github.hook.before('request', async (options) => {
validate(options)
})
github.hook.after('request', async (response, options) => {
console.log(`${options.method} ${options.url}: ${response.status}`)
})
github.hook.error('request', async (error, options) => {
if (error.status === 304) {
return findInCache(error.headers.etag)
}
throw error
})
github.hook.wrap('request', async (request, options) => {
// add logic before, after, catch errors or replace the request altogether
return request(options)
})See before-after-hook for more documentation on hooks.
You can customize and extend Octokit’s functionality using plugins
// index.js
const MyOctokit = require('@octokit/request')
.plugin([
require('./lib/my-plugin'),
require('octokit-plugin-example')
])
// lib/my-plugin.js
module.exports = (octokit, options = { greeting: 'Hello' }) => {
// add a custom method
octokit.helloWorld = () => console.log(`${options.greeting}, world!`)
// hook into the request lifecycle
octokit.hook.wrap('request', async (request, options) => {
const time = Date.now()
const response = await request(options)
console.log(`${options.method} ${options.url} – ${response.status} in ${Date.now() - time}ms`)
return response
})
}.plugin accepts a function or an array of functions.
You can add new methods to the octokit instance passed as the first argument to
the plugin function. The 2nd argument is the options object passed to the
constructor when instantiating the octokit client.
const octokit = new MyOctokit({ greeting: 'Hola' })
octokit.helloWorld()
// Hola, world!You can register custom endpoint methods such as octokit.repos.get() using
the octokit.registerEndpoints(routes) method
octokit.registerEndpoints({
foo: {
bar: {
method: 'PATCH',
url: '/repos/:owner/:repo/foo',
headers: {
accept: 'application/vnd.github.foo-bar-preview+json'
},
params: {
owner: {
required: true,
type: 'string'
},
repo: {
required: true,
type: 'string'
},
baz: {
required: true,
type: 'string',
enum: [
'qux',
'quux',
'quuz'
]
}
}
}
}
})
octokit.foo.bar({
owner: 'octokit',
repo: 'rest.js',
baz: 'quz'
})This is useful when you participate in private beta features and prefer the
convenience of methods for the new endpoints instead of using octokit.request().
When you send too many requests in too little time you will likely hit errors due to quotas.
In order to automatically throttle requests as recommended in the best practices for integrators, we recommend you install the @octokit/plugin-throttling plugin.
The throttle.onAbuseLimit and throttle.onRateLimit options are required. Return true to automatically retry the request after retryAfter seconds.
const Octokit = require('@octokit/rest')
.plugin(require('@octokit/plugin-throttling'))
const octokit = new Octokit({
throttle: {
onRateLimit: (retryAfter, options) => {
console.warn(`Request quota exhausted for request ${options.method} ${options.url}`)
if (options.request.retryCount === 0) { // only retries once
console.log(`Retrying after ${retryAfter} seconds!`)
return true
}
},
onAbuseLimit: (retryAfter, options) => {
// does not retry, only logs a warning
console.warn(`Abuse detected for request ${options.method} ${options.url}`)
}
}
})
octokit.authenticate({
type: 'token',
token: process.env.TOKEN
})Many common request errors can be easily remediated by retrying the request. We recommend installing the @octokit/plugin-retry plugin for Automatic retries in these cases
const Octokit = require('@octokit/rest')
.plugin(require('@octokit/plugin-retry'))
const octokit = new Octokit()
// all requests sent with the `octokit` instance are now retried up to 3 times for recoverable errors.Set DEBUG=octokit:rest* for additional debug logs.
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