@octokit/rest

rest.js

GitHub REST API client for JavaScript

Usage

Node

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, headers, status }) => {
  // handle data
})

Browser

• Download octokit-rest.min.js from 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 octokit

  const 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
  })
  

Client options

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

@octokit/rest API docs: https://octokit.github.io/rest.js/
GitHub v3 REST API docs: https://developer.github.com/v3/

API Previews

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 } } = 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 } } = octokit.repos.get({
  owner: 'octokit',
  repo: 'rest.js',
  headers: {
    accept: 'application/vnd.github.mercy-preview+json,application/vnd.github.scarlet-witch-preview+json'
  }
})

Authentication

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: 'app',
  token: 'secrettoken123'
})

Note: authenticate is synchronous because it only sets the credentials for the following requests.

Pagination

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

Debug

Set DEBUG=octokit:rest* for additional debug logs.

Tests

Before running any tests you have to start the fixtures server

$ npm run start-fixtures-server

In a second terminal, run the tests

$ npm test

Or run a specific test

$ ./node_modules/.bin/mocha test/scenarios/get-repository-test.js

Run browser tests

$ npm run test:browser

Note: In order to run the same scenario tests in both Node and browser, we simulate the Cypress environment in Node, see test/mocha-node-setup.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.

Contributing

We would love you to contribute to @octokit/rest, pull requests are very welcomed! Please see CONTRIBUTING.md for more information.

Credits

@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

LICENSE

MIT

Similar packages

Other packages similar to @octokit/rest

github

The 'github' npm package is another client library for the GitHub API. It offers similar functionalities to @octokit/rest but has been deprecated in favor of @octokit/rest, which is its direct successor. @octokit/rest provides a more modern and feature-rich interface.

node-github

The 'node-github' package is an older client for the GitHub API, offering basic functionalities to interact with GitHub resources. Compared to @octokit/rest, it might not be as up-to-date or feature-rich, as @octokit/rest is the official client library recommended by GitHub.