1 | # endpoint.js
|
2 |
|
3 | > Turns GitHub REST API endpoints into generic request options
|
4 |
|
5 | [![@latest](https://img.shields.io/npm/v/@octokit/endpoint.svg)](https://www.npmjs.com/package/@octokit/endpoint)
|
6 | ![Build Status](https://github.com/octokit/endpoint.js/workflows/Test/badge.svg)
|
7 |
|
8 | `@octokit/endpoint` combines [GitHub REST API routes](https://developer.github.com/v3/) with your parameters and turns them into generic request options that can be used in any request library.
|
9 |
|
10 |
|
11 |
|
12 |
|
13 |
|
14 | - [Usage](#usage)
|
15 | - [API](#api)
|
16 | - [`endpoint(route, options)` or `endpoint(options)`](#endpointroute-options-or-endpointoptions)
|
17 | - [`endpoint.defaults()`](#endpointdefaults)
|
18 | - [`endpoint.DEFAULTS`](#endpointdefaults)
|
19 | - [`endpoint.merge(route, options)` or `endpoint.merge(options)`](#endpointmergeroute-options-or-endpointmergeoptions)
|
20 | - [`endpoint.parse()`](#endpointparse)
|
21 | - [Special cases](#special-cases)
|
22 | - [The `data` parameter – set request body directly](#the-data-parameter-%E2%80%93-set-request-body-directly)
|
23 | - [Set parameters for both the URL/query and the request body](#set-parameters-for-both-the-urlquery-and-the-request-body)
|
24 | - [LICENSE](#license)
|
25 |
|
26 |
|
27 |
|
28 | ## Usage
|
29 |
|
30 | <table>
|
31 | <tbody valign=top align=left>
|
32 | <tr><th>
|
33 | Browsers
|
34 | </th><td width=100%>
|
35 | Load <code>@octokit/endpoint</code> directly from <a href="https://cdn.skypack.dev">cdn.skypack.dev</a>
|
36 |
|
37 | ```html
|
38 | <script type="module">
|
39 | import { endpoint } from "https://cdn.skypack.dev/@octokit/endpoint";
|
40 | </script>
|
41 | ```
|
42 |
|
43 | </td></tr>
|
44 | <tr><th>
|
45 | Node
|
46 | </th><td>
|
47 |
|
48 | Install with <code>npm install @octokit/endpoint</code>
|
49 |
|
50 | ```js
|
51 | const { endpoint } = require("@octokit/endpoint");
|
52 | // or: import { endpoint } from "@octokit/endpoint";
|
53 | ```
|
54 |
|
55 | </td></tr>
|
56 | </tbody>
|
57 | </table>
|
58 |
|
59 | Example for [List organization repositories](https://developer.github.com/v3/repos/#list-organization-repositories)
|
60 |
|
61 | ```js
|
62 | const requestOptions = endpoint("GET /orgs/{org}/repos", {
|
63 | headers: {
|
64 | authorization: "token 0000000000000000000000000000000000000001",
|
65 | },
|
66 | org: "octokit",
|
67 | type: "private",
|
68 | });
|
69 | ```
|
70 |
|
71 | The resulting `requestOptions` looks as follows
|
72 |
|
73 | ```json
|
74 | {
|
75 | "method": "GET",
|
76 | "url": "https://api.github.com/orgs/octokit/repos?type=private",
|
77 | "headers": {
|
78 | "accept": "application/vnd.github.v3+json",
|
79 | "authorization": "token 0000000000000000000000000000000000000001",
|
80 | "user-agent": "octokit/endpoint.js v1.2.3"
|
81 | }
|
82 | }
|
83 | ```
|
84 |
|
85 | You can pass `requestOptions` to common request libraries
|
86 |
|
87 | ```js
|
88 | const { url, ...options } = requestOptions;
|
89 | // using with fetch (https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
|
90 | fetch(url, options);
|
91 | // using with request (https://github.com/request/request)
|
92 | request(requestOptions);
|
93 | // using with got (https://github.com/sindresorhus/got)
|
94 | got[options.method](url, options);
|
95 | // using with axios
|
96 | axios(requestOptions);
|
97 | ```
|
98 |
|
99 | ## API
|
100 |
|
101 | ### `endpoint(route, options)` or `endpoint(options)`
|
102 |
|
103 | <table>
|
104 | <thead align=left>
|
105 | <tr>
|
106 | <th>
|
107 | name
|
108 | </th>
|
109 | <th>
|
110 | type
|
111 | </th>
|
112 | <th width=100%>
|
113 | description
|
114 | </th>
|
115 | </tr>
|
116 | </thead>
|
117 | <tbody align=left valign=top>
|
118 | <tr>
|
119 | <th>
|
120 | <code>route</code>
|
121 | </th>
|
122 | <td>
|
123 | String
|
124 | </td>
|
125 | <td>
|
126 | If set, it has to be a string consisting of URL and the request method, e.g., <code>GET /orgs/{org}</code>. If it’s set to a URL, only the method defaults to <code>GET</code>.
|
127 | </td>
|
128 | </tr>
|
129 | <tr>
|
130 | <th>
|
131 | <code>options.method</code>
|
132 | </th>
|
133 | <td>
|
134 | String
|
135 | </td>
|
136 | <td>
|
137 | <strong>Required unless <code>route</code> is set.</strong> Any supported <a href="https://developer.github.com/v3/#http-verbs">http verb</a>. <em>Defaults to <code>GET</code></em>.
|
138 | </td>
|
139 | </tr>
|
140 | <tr>
|
141 | <th>
|
142 | <code>options.url</code>
|
143 | </th>
|
144 | <td>
|
145 | String
|
146 | </td>
|
147 | <td>
|
148 | <strong>Required unless <code>route</code> is set.</strong> A path or full URL which may contain <code>:variable</code> or <code>{variable}</code> placeholders,
|
149 | e.g., <code>/orgs/{org}/repos</code>. The <code>url</code> is parsed using <a href="https://github.com/bramstein/url-template">url-template</a>.
|
150 | </td>
|
151 | </tr>
|
152 | <tr>
|
153 | <th>
|
154 | <code>options.baseUrl</code>
|
155 | </th>
|
156 | <td>
|
157 | String
|
158 | </td>
|
159 | <td>
|
160 | <em>Defaults to <code>https://api.github.com</code></em>.
|
161 | </td>
|
162 | </tr>
|
163 | <tr>
|
164 | <th>
|
165 | <code>options.headers</code>
|
166 | </th>
|
167 | <td>
|
168 | Object
|
169 | </td>
|
170 | <td>
|
171 | Custom headers. Passed headers are merged with defaults:<br>
|
172 | <em><code>headers['user-agent']</code> defaults to <code>octokit-endpoint.js/1.2.3</code> (where <code>1.2.3</code> is the released version)</em>.<br>
|
173 | <em><code>headers['accept']</code> defaults to <code>application/vnd.github.v3+json</code></em>.<br>
|
174 | </td>
|
175 | </tr>
|
176 | <tr>
|
177 | <th>
|
178 | <code>options.mediaType.format</code>
|
179 | </th>
|
180 | <td>
|
181 | String
|
182 | </td>
|
183 | <td>
|
184 | Media type param, such as <code>raw</code>, <code>diff</code>, or <code>text+json</code>. See <a href="https://developer.github.com/v3/media/">Media Types</a>. Setting <code>options.mediaType.format</code> will amend the <code>headers.accept</code> value.
|
185 | </td>
|
186 | </tr>
|
187 | <tr>
|
188 | <th>
|
189 | <code>options.mediaType.previews</code>
|
190 | </th>
|
191 | <td>
|
192 | Array of Strings
|
193 | </td>
|
194 | <td>
|
195 | Name of previews, such as <code>mercy</code>, <code>symmetra</code>, or <code>scarlet-witch</code>. See <a href="https://developer.github.com/v3/previews/">API Previews</a>. If <code>options.mediaType.previews</code> was set as default, the new previews will be merged into the default ones. Setting <code>options.mediaType.previews</code> will amend the <code>headers.accept</code> value. <code>options.mediaType.previews</code> will be merged with an existing array set using <code>.defaults()</code>.
|
196 | </td>
|
197 | </tr>
|
198 | <tr>
|
199 | <th>
|
200 | <code>options.data</code>
|
201 | </th>
|
202 | <td>
|
203 | Any
|
204 | </td>
|
205 | <td>
|
206 | Set request body directly instead of setting it to JSON based on additional parameters. See <a href="#data-parameter">"The <code>data</code> parameter"</a> below.
|
207 | </td>
|
208 | </tr>
|
209 | <tr>
|
210 | <th>
|
211 | <code>options.request</code>
|
212 | </th>
|
213 | <td>
|
214 | Object
|
215 | </td>
|
216 | <td>
|
217 | Pass custom meta information for the request. The <code>request</code> object will be returned as is.
|
218 | </td>
|
219 | </tr>
|
220 | </tbody>
|
221 | </table>
|
222 |
|
223 | All other options will be passed depending on the `method` and `url` options.
|
224 |
|
225 | 1. If the option key has a placeholder in the `url`, it will be used as the replacement. For example, if the passed options are `{url: '/orgs/{org}/repos', org: 'foo'}` the returned `options.url` is `https://api.github.com/orgs/foo/repos`.
|
226 | 2. If the `method` is `GET` or `HEAD`, the option is passed as a query parameter.
|
227 | 3. Otherwise, the parameter is passed in the request body as a JSON key.
|
228 |
|
229 | **Result**
|
230 |
|
231 | `endpoint()` is a synchronous method and returns an object with the following keys:
|
232 |
|
233 | <table>
|
234 | <thead align=left>
|
235 | <tr>
|
236 | <th>
|
237 | key
|
238 | </th>
|
239 | <th>
|
240 | type
|
241 | </th>
|
242 | <th width=100%>
|
243 | description
|
244 | </th>
|
245 | </tr>
|
246 | </thead>
|
247 | <tbody align=left valign=top>
|
248 | <tr>
|
249 | <th><code>method</code></th>
|
250 | <td>String</td>
|
251 | <td>The http method. Always lowercase.</td>
|
252 | </tr>
|
253 | <tr>
|
254 | <th><code>url</code></th>
|
255 | <td>String</td>
|
256 | <td>The url with placeholders replaced with passed parameters.</td>
|
257 | </tr>
|
258 | <tr>
|
259 | <th><code>headers</code></th>
|
260 | <td>Object</td>
|
261 | <td>All header names are lowercased.</td>
|
262 | </tr>
|
263 | <tr>
|
264 | <th><code>body</code></th>
|
265 | <td>Any</td>
|
266 | <td>The request body if one is present. Only for <code>PATCH</code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code> requests.</td>
|
267 | </tr>
|
268 | <tr>
|
269 | <th><code>request</code></th>
|
270 | <td>Object</td>
|
271 | <td>Request meta option, it will be returned as it was passed into <code>endpoint()</code></td>
|
272 | </tr>
|
273 | </tbody>
|
274 | </table>
|
275 |
|
276 | ### `endpoint.defaults()`
|
277 |
|
278 | Override or set default options. Example:
|
279 |
|
280 | ```js
|
281 | const request = require("request");
|
282 | const myEndpoint = require("@octokit/endpoint").defaults({
|
283 | baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
|
284 | headers: {
|
285 | "user-agent": "myApp/1.2.3",
|
286 | authorization: `token 0000000000000000000000000000000000000001`,
|
287 | },
|
288 | org: "my-project",
|
289 | per_page: 100,
|
290 | });
|
291 |
|
292 | request(myEndpoint(`GET /orgs/{org}/repos`));
|
293 | ```
|
294 |
|
295 | You can call `.defaults()` again on the returned method, the defaults will cascade.
|
296 |
|
297 | ```js
|
298 | const myProjectEndpoint = endpoint.defaults({
|
299 | baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
|
300 | headers: {
|
301 | "user-agent": "myApp/1.2.3",
|
302 | },
|
303 | org: "my-project",
|
304 | });
|
305 | const myProjectEndpointWithAuth = myProjectEndpoint.defaults({
|
306 | headers: {
|
307 | authorization: `token 0000000000000000000000000000000000000001`,
|
308 | },
|
309 | });
|
310 | ```
|
311 |
|
312 | `myProjectEndpointWithAuth` now defaults the `baseUrl`, `headers['user-agent']`,
|
313 | `org` and `headers['authorization']` on top of `headers['accept']` that is set
|
314 | by the global default.
|
315 |
|
316 | ### `endpoint.DEFAULTS`
|
317 |
|
318 | The current default options.
|
319 |
|
320 | ```js
|
321 | endpoint.DEFAULTS.baseUrl; // https://api.github.com
|
322 | const myEndpoint = endpoint.defaults({
|
323 | baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
|
324 | });
|
325 | myEndpoint.DEFAULTS.baseUrl; // https://github-enterprise.acme-inc.com/api/v3
|
326 | ```
|
327 |
|
328 | ### `endpoint.merge(route, options)` or `endpoint.merge(options)`
|
329 |
|
330 | Get the defaulted endpoint options, but without parsing them into request options:
|
331 |
|
332 | ```js
|
333 | const myProjectEndpoint = endpoint.defaults({
|
334 | baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
|
335 | headers: {
|
336 | "user-agent": "myApp/1.2.3",
|
337 | },
|
338 | org: "my-project",
|
339 | });
|
340 | myProjectEndpoint.merge("GET /orgs/{org}/repos", {
|
341 | headers: {
|
342 | authorization: `token 0000000000000000000000000000000000000001`,
|
343 | },
|
344 | org: "my-secret-project",
|
345 | type: "private",
|
346 | });
|
347 |
|
348 | // {
|
349 | // baseUrl: 'https://github-enterprise.acme-inc.com/api/v3',
|
350 | // method: 'GET',
|
351 | // url: '/orgs/{org}/repos',
|
352 | // headers: {
|
353 | // accept: 'application/vnd.github.v3+json',
|
354 | // authorization: `token 0000000000000000000000000000000000000001`,
|
355 | // 'user-agent': 'myApp/1.2.3'
|
356 | // },
|
357 | // org: 'my-secret-project',
|
358 | // type: 'private'
|
359 | // }
|
360 | ```
|
361 |
|
362 | ### `endpoint.parse()`
|
363 |
|
364 | Stateless method to turn endpoint options into request options. Calling
|
365 | `endpoint(options)` is the same as calling `endpoint.parse(endpoint.merge(options))`.
|
366 |
|
367 | ## Special cases
|
368 |
|
369 | <a name="data-parameter"></a>
|
370 |
|
371 | ### The `data` parameter – set request body directly
|
372 |
|
373 | Some endpoints such as [Render a Markdown document in raw mode](https://developer.github.com/v3/markdown/#render-a-markdown-document-in-raw-mode) don’t have parameters that are sent as request body keys, instead, the request body needs to be set directly. In these cases, set the `data` parameter.
|
374 |
|
375 | ```js
|
376 | const options = endpoint("POST /markdown/raw", {
|
377 | data: "Hello world github/linguist#1 **cool**, and #1!",
|
378 | headers: {
|
379 | accept: "text/html;charset=utf-8",
|
380 | "content-type": "text/plain",
|
381 | },
|
382 | });
|
383 |
|
384 | // options is
|
385 | // {
|
386 | // method: 'post',
|
387 | // url: 'https://api.github.com/markdown/raw',
|
388 | // headers: {
|
389 | // accept: 'text/html;charset=utf-8',
|
390 | // 'content-type': 'text/plain',
|
391 | // 'user-agent': userAgent
|
392 | // },
|
393 | // body: 'Hello world github/linguist#1 **cool**, and #1!'
|
394 | // }
|
395 | ```
|
396 |
|
397 | ### Set parameters for both the URL/query and the request body
|
398 |
|
399 | There are API endpoints that accept both query parameters as well as a body. In that case, you need to add the query parameters as templates to `options.url`, as defined in the [RFC 6570 URI Template specification](https://tools.ietf.org/html/rfc6570).
|
400 |
|
401 | Example
|
402 |
|
403 | ```js
|
404 | endpoint(
|
405 | "POST https://uploads.github.com/repos/octocat/Hello-World/releases/1/assets{?name,label}",
|
406 | {
|
407 | name: "example.zip",
|
408 | label: "short description",
|
409 | headers: {
|
410 | "content-type": "text/plain",
|
411 | "content-length": 14,
|
412 | authorization: `token 0000000000000000000000000000000000000001`,
|
413 | },
|
414 | data: "Hello, world!",
|
415 | }
|
416 | );
|
417 | ```
|
418 |
|
419 | ## LICENSE
|
420 |
|
421 | [MIT](LICENSE)
|