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