- [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).
**Required**. If <code>route</code> is set it has to be a string consisting of the request method and URL, e.g. <code>GET /orgs/{org}</code>
</td>
</tr>
<tr>
<thalign=left>
<code>options.baseUrl</code>
</th>
<td>
String
</td>
<td>
The base URL that <code>route</code> or <code>url</code> will be prefixed with, if they use relative paths. <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>
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>
**Required**. A path or full URL which may contain <code>:variable</code> or <code>{variable}</code> placeholders,
e.g. <code>/orgs/{org}/repos</code>. The <code>url</code> is parsed using <ahref="https://github.com/bramstein/url-template">url-template</a>.
</td>
</tr>
<tr>
<thalign=left>
<code>options.data</code>
</th>
<td>
Any
</td>
<td>
Set request body directly instead of setting it to JSON based on additional parameters. See <ahref="#data-parameter">"The `data` parameter"</a> below.
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>
<thalign=left>
<code>options.request.log</code>
</th>
<td>
<code>object</code>
</td>
<td>
Used for internal logging. Defaults to <ahref="https://developer.mozilla.org/en-US/docs/Web/API/console"><code>console</code></a>.
</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.
<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>
### 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).
