github.com/nektos/act@v0.2.63/pkg/runner/testdata/actions/node12/node_modules/@octokit/endpoint/README.md (about) 1 # endpoint.js 2 3 > Turns GitHub REST API endpoints into generic request options 4 5 [](https://www.npmjs.com/package/@octokit/endpoint) 6  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 <!-- update table of contents by running `npx markdown-toc README.md -i` --> 11 12 <!-- toc --> 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 <!-- tocstop --> 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)