1 | # rest.js [![@latest](https://img.shields.io/npm/v/@octokit/rest.svg)](https://www.npmjs.com/package/@octokit/rest) [![@next](https://img.shields.io/npm/v/@octokit/rest/next.svg?label=@next)](https://www.npmjs.com/package/@octokit/rest)
|
2 |
|
3 | > GitHub REST API client for Node.js
|
4 |
|
5 | [![Build Status](https://travis-ci.org/octokit/rest.js.svg?branch=master)](https://travis-ci.org/octokit/rest.js)
|
6 | [![Coverage Status](https://coveralls.io/repos/github/octokit/rest.js/badge.svg)](https://coveralls.io/github/octokit/rest.js)
|
7 | [![Greenkeeper](https://badges.greenkeeper.io/octokit/rest.js.svg)](https://greenkeeper.io/)
|
8 |
|
9 | ## Usage
|
10 |
|
11 | ### Node
|
12 |
|
13 | Install with `npm install @octokit/rest`.
|
14 |
|
15 | ```js
|
16 | const octokit = require('@octokit/rest')()
|
17 |
|
18 | // Compare: https://developer.github.com/v3/repos/#list-organization-repositories
|
19 | octokit.repos.getForOrg({
|
20 | org: 'octokit',
|
21 | type: 'public'
|
22 | }).then(({data}) => {
|
23 | // handle data
|
24 | })
|
25 | ```
|
26 |
|
27 | ### Browser
|
28 |
|
29 | 1. Download `octokit-rest.min.js` from the latest release: https://github.com/octokit/rest.js/releases
|
30 |
|
31 | 2. Load it as script into your web application:
|
32 |
|
33 | ```html
|
34 | <script scr="octokit-rest.min.js"></script>
|
35 | ```
|
36 |
|
37 | 3. Initialize `octokit`
|
38 |
|
39 | ```js
|
40 | const octokit = new Octokit()
|
41 |
|
42 | // Compare: https://developer.github.com/v3/repos/#list-organization-repositories
|
43 | octokit.repos.getForOrg({
|
44 | org: 'octokit',
|
45 | type: 'public'
|
46 | }).then(({data}) => {
|
47 | // handle data
|
48 | })
|
49 | ```
|
50 |
|
51 | ### Options
|
52 |
|
53 | All available client options with default values
|
54 |
|
55 | <!-- HEADS UP: when changing the options for the constructor, make sure to also
|
56 | update the type definition templates in scripts/templates/* -->
|
57 | ```js
|
58 | const octokit = require('@octokit/rest')({
|
59 | timeout: 0, // 0 means no request timeout
|
60 | requestMedia: 'application/vnd.github.v3+json',
|
61 | headers: {
|
62 | 'user-agent': 'octokit/rest.js v1.2.3' // v1.2.3 will be current version
|
63 | },
|
64 |
|
65 | // change for custom GitHub Enterprise URL
|
66 | host: 'api.github.com',
|
67 | pathPrefix: '',
|
68 | protocol: 'https',
|
69 | port: 443,
|
70 |
|
71 | // Node only: advanced request options can be passed as http(s) agent
|
72 | agent: undefined
|
73 | })
|
74 | ```
|
75 |
|
76 | `@octokit/rest` API docs: https://octokit.github.io/rest.js/
|
77 | GitHub v3 REST API docs: https://developer.github.com/v3/
|
78 |
|
79 | ## Authentication
|
80 |
|
81 | Most GitHub API calls don't require authentication. Rules of thumb:
|
82 |
|
83 | 1. 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.
|
84 | 2. If you want to change data, you have to be authenticated.
|
85 |
|
86 | ```javascript
|
87 | // basic
|
88 | octokit.authenticate({
|
89 | type: 'basic',
|
90 | username: 'yourusername',
|
91 | password: 'password'
|
92 | })
|
93 |
|
94 | // oauth
|
95 | octokit.authenticate({
|
96 | type: 'oauth',
|
97 | token: 'secrettoken123'
|
98 | })
|
99 |
|
100 | // oauth key/secret (to get a token)
|
101 | octokit.authenticate({
|
102 | type: 'oauth',
|
103 | key: 'client_id',
|
104 | secret: 'client_secret'
|
105 | })
|
106 |
|
107 | // token (https://github.com/settings/tokens)
|
108 | octokit.authenticate({
|
109 | type: 'token',
|
110 | token: 'secrettoken123'
|
111 | })
|
112 |
|
113 | // GitHub app
|
114 | octokit.authenticate({
|
115 | type: 'integration',
|
116 | token: 'secrettoken123'
|
117 | })
|
118 | ```
|
119 |
|
120 | Note: `authenticate` is synchronous because it only sets the credentials
|
121 | for the following requests.
|
122 |
|
123 | ## Pagination
|
124 |
|
125 | There are a few pagination-related methods:
|
126 |
|
127 | - `hasNextPage(response)`
|
128 | - `hasPreviousPage(response)`
|
129 | - `hasFirstPage(response)`
|
130 | - `hasLastPage(response)`
|
131 | - `getNextPage(response)`
|
132 | - `getPreviousPage(response)`
|
133 | - `getFirstPage(response)`
|
134 | - `getLastPage(response)`
|
135 |
|
136 | Usage
|
137 |
|
138 | ```js
|
139 | async function paginate (method) {
|
140 | let response = await method({per_page: 100})
|
141 | let {data} = response
|
142 | while (octokit.hasNextPage(response)) {
|
143 | response = await octokit.getNextPage(response)
|
144 | data = data.concat(response.data)
|
145 | }
|
146 | return data
|
147 | }
|
148 |
|
149 | paginate(octokit.repos.getAll)
|
150 | .then(data => {
|
151 | // handle all results
|
152 | })
|
153 | ```
|
154 |
|
155 | ## Debug
|
156 |
|
157 | Set `DEBUG=octokit:rest*` for additional debug logs.
|
158 |
|
159 | ## Tests
|
160 |
|
161 | Before running any tests you have to start the [fixtures server](https://github.com/octokit/fixtures-server)
|
162 |
|
163 | ```
|
164 | $ npm run start-fixtures-server
|
165 | ```
|
166 |
|
167 | In a second terminal, run the tests
|
168 |
|
169 | ```bash
|
170 | $ npm test
|
171 | ```
|
172 |
|
173 | Or run a specific test
|
174 |
|
175 | ```bash
|
176 | $ ./node_modules/.bin/mocha test/scenarios/get-repository-test.js
|
177 | ```
|
178 |
|
179 | Run browser tests
|
180 |
|
181 | ```bash
|
182 | $ npm run test:browser
|
183 | ```
|
184 |
|
185 | **Note**: In order to run the same [scenario tests](test/scenarios) in both Node
|
186 | and browser, we simulate the Cypress environment in Node, see [test/mocha-node-setup.js](test/mocha-node-setup.js).
|
187 |
|
188 | The examples are run as part of the tests. You can set an `EXAMPLES_GITHUB_TOKEN` environment
|
189 | variable (or set it in a `.env` file) to avoid running against GitHub's rate limit.
|
190 |
|
191 | ## Contributing
|
192 |
|
193 | We would love you to contribute to `@octokit/rest`, pull requests are very welcomed!
|
194 | Please see [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
|
195 |
|
196 | ## Credits
|
197 |
|
198 | `@octokit/rest` was originally created as [`node-github`](https://www.npmjs.com/package/github)
|
199 | in 2012 by Mike de Boer from Cloud9 IDE, Inc.
|
200 | It was adopted and renamed by GitHub in 2017
|
201 |
|
202 | ## LICENSE
|
203 |
|
204 | [MIT](LICENSE)
|