It uses [`@octokit/endpoint`](https://github.com/octokit/endpoint.js) to parse
the passed options and sends the request using [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
([node-fetch](https://github.com/bitinn/node-fetch) in Node).
<!-- update table of contents by running `npx markdown-toc README.md -i` -->
<!-- toc -->
- [Features](#features)
- [Usage](#usage)
- [REST API example](#rest-api-example)
- [GraphQL example](#graphql-example)
- [Alternative: pass `method` & `url` as part of options](#alternative-pass-method--url-as-part-of-options)
- [Authentication](#authentication)
- [request()](#request)
- [`request.defaults()`](#requestdefaults)
- [`request.endpoint`](#requestendpoint)
- [Special cases](#special-cases)
- [The `data` parameter – set request body directly](#the-data-parameter-%E2%80%93-set-request-body-directly)
- [Set parameters for both the URL/query and the request body](#set-parameters-for-both-the-urlquery-and-the-request-body)
- [LICENSE](#license)
<!-- tocstop -->
## Features
🤩 1:1 mapping of REST API endpoint documentation, e.g. [Add labels to an issue](https://developer.github.com/v3/issues/labels/#add-labels-to-an-issue) becomes
The simplest way to authenticate a request is to set the `Authorization` header directly, e.g. to a [personal access token](https://github.com/settings/tokens/).
const result = await requestWithAuth("GET /user");
```
For more complex authentication strategies such as GitHub Apps or Basic, we recommend the according authentication library exported by [`@octokit/auth`](https://github.com/octokit/auth.js).
<strong>Required.</strong> Any supported <ahref="https://developer.github.com/v3/#http-verbs">http verb</a>, case insensitive. <em>Defaults to <code>https://api.github.com</code></em>.
</td>
</tr>
<thalign=left>
<code>options.headers</code>
</th>
<td>
Object
</td>
<td>
Custom headers. Passed headers are merged with defaults:<br>
<em><code>headers['user-agent']</code> defaults to <code>octokit-rest.js/1.2.3</code> (where <code>1.2.3</code> is the released version)</em>.<br>
<em><code>headers['accept']</code> defaults to <code>application/vnd.github.v3+json</code>.<br> Use <code>options.mediaType.{format,previews}</code> to request API previews and custom media types.
</td>
</tr>
<tr>
<thalign=left>
<code>options.mediaType.format</code>
</th>
<td>
String
</td>
<td>
Media type param, such as `raw`, `html`, or `full`. See <ahref="https://developer.github.com/v3/media/">Media Types</a>.
</td>
</tr>
<tr>
<thalign=left>
<code>options.mediaType.previews</code>
</th>
<td>
Array of strings
</td>
<td>
Name of previews, such as `mercy`, `symmetra`, or `scarlet-witch`. See <ahref="https://developer.github.com/v3/previews/">API Previews</a>.
</td>
</tr>
<tr>
<thalign=left>
<code>options.method</code>
</th>
<td>
String
</td>
<td>
<strong>Required.</strong> Any supported <ahref="https://developer.github.com/v3/#http-verbs">http verb</a>, case insensitive. <em>Defaults to <code>Get</code></em>.
</td>
</tr>
<tr>
<thalign=left>
<code>options.url</code>
</th>
<td>
String
</td>
<td>
<strong>Required.</strong> A path or full URL which may contain <code>:variable</code> or <code>{variable}</code> placeholders,
Node only. Useful for custom proxy, certificate, or dns lookup.
</td>
</tr>
<tr>
<thalign=left>
<code>options.request.fetch</code>
</th>
<td>
Function
</td>
<td>
Custom replacement for <ahref="https://github.com/bitinn/node-fetch">built-in fetch method</a>. Useful for testing or request hooks.
</td>
</tr>
<tr>
<thalign=left>
<code>options.request.hook</code>
</th>
<td>
Function
</td>
<td>
Function with the signature <code>hook(request, endpointOptions)</code>, where <code>endpointOptions</code> are the parsed options as returned by <ahref="https://github.com/octokit/endpoint.js#endpointmergeroute-options-or-endpointmergeoptions"><code>endpoint.merge()</code></a>, and <code>request</code> is <ahref="https://github.com/octokit/request.js#request"><code>request()</code></a>. This option works great in conjuction with <ahref="https://github.com/gr2m/before-after-hook">before-after-hook</a>.
Use an <code>AbortController</code> instance to cancel a request. In node you can only cancel streamed requests.
</td>
</tr>
<tr>
<thalign=left>
<code>options.request.timeout</code>
</th>
<td>
Number
</td>
<td>
Node only. Request/response timeout in ms, it resets on redirect. 0 to disable (OS limit applies). <ahref="#options-request-signal">options.request.signal</a> is recommended instead.
</td>
</tr>
</table>
All other options except `options.request.*` will be passed depending on the `method` and `url` options.
1. If the option key is a placeholder in the `url`, it will be used as 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`
2. If the `method` is `GET` or `HEAD`, the option is passed as query parameter
3. Otherwise the parameter is passed in the request body as JSON key.
**Result**
`request` returns a promise and resolves with 4 keys
<table>
<thead>
<tr>
<thalign=left>
key
</th>
<thalign=left>
type
</th>
<thalign=left>
description
</th>
</tr>
</thead>
<tr>
<thalign=left><code>status</code></th>
<td>Integer</td>
<td>Response status status</td>
</tr>
<tr>
<thalign=left><code>url</code></th>
<td>String</td>
<td>URL of response. If a request results in redirects, this is the final URL. You can send a <code>HEAD</code> request to retrieve it without loading the full response body.</td>
</tr>
<tr>
<thalign=left><code>headers</code></th>
<td>Object</td>
<td>All response headers</td>
</tr>
<tr>
<thalign=left><code>data</code></th>
<td>Any</td>
<td>The response body as returned from server. If the response is JSON then it will be parsed into an object</td>
</tr>
</table>
If an error occurs, the `error` instance has additional properties to help with debugging
-`error.status` The http response status code
-`error.headers` The http response headers as an object
-`error.request` The request options such as `method`, `url` and `data`
### The `data` parameter – set request body directly
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.
data: "Hello world github/linguist#1 **cool**, and #1!",
headers: {
accept: "text/html;charset=utf-8",
"content-type": "text/plain",
},
});
// Request is sent as
//
// {
// method: 'post',
// url: 'https://api.github.com/markdown/raw',
// headers: {
// accept: 'text/html;charset=utf-8',
// 'content-type': 'text/plain',
// 'user-agent': userAgent
// },
// body: 'Hello world github/linguist#1 **cool**, and #1!'
// }
//
// not as
//
// {
// ...
// body: '{"data": "Hello world github/linguist#1 **cool**, and #1!"}'
// }
```
### Set parameters for both the URL/query and the request body
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).
