`@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.
<!-- update table of contents by running `npx markdown-toc README.md -i` -->
<!-- toc -->
- [Usage](#usage)
- [API](#api)
- [`endpoint(route, options)` or `endpoint(options)`](#endpointroute-options-or-endpointoptions)
- [`endpoint.defaults()`](#endpointdefaults)
- [`endpoint.DEFAULTS`](#endpointdefaults)
- [`endpoint.merge(route, options)` or `endpoint.merge(options)`](#endpointmergeroute-options-or-endpointmergeoptions)
- [`endpoint.parse()`](#endpointparse)
- [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 -->
## Usage
<table>
<tbodyvalign=topalign=left>
<tr><th>
Browsers
</th><tdwidth=100%>
Load <code>@octokit/endpoint</code> directly from <ahref="https://cdn.skypack.dev">cdn.skypack.dev</a>
```html
<scripttype="module">
import { endpoint } from "https://cdn.skypack.dev/@octokit/endpoint";
</script>
```
</td></tr>
<tr><th>
Node
</th><td>
Install with <code>npm install @octokit/endpoint</code>
You can pass `requestOptions` to common request libraries
```js
const { url, ...options } = requestOptions;
// using with fetch (https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
fetch(url, options);
// using with request (https://github.com/request/request)
request(requestOptions);
// using with got (https://github.com/sindresorhus/got)
got[options.method](url, options);
// using with axios
axios(requestOptions);
```
## API
### `endpoint(route, options)` or `endpoint(options)`
<table>
<theadalign=left>
<tr>
<th>
name
</th>
<th>
type
</th>
<thwidth=100%>
description
</th>
</tr>
</thead>
<tbodyalign=leftvalign=top>
<tr>
<th>
<code>route</code>
</th>
<td>
String
</td>
<td>
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>.
</td>
</tr>
<tr>
<th>
<code>options.method</code>
</th>
<td>
String
</td>
<td>
<strong>Required unless <code>route</code> is set.</strong> Any supported <ahref="https://developer.github.com/v3/#http-verbs">http verb</a>. <em>Defaults to <code>GET</code></em>.
</td>
</tr>
<tr>
<th>
<code>options.url</code>
</th>
<td>
String
</td>
<td>
<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,
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>
<th>
<code>options.baseUrl</code>
</th>
<td>
String
</td>
<td>
<em>Defaults to <code>https://api.github.com</code></em>.
</td>
</tr>
<tr>
<th>
<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-endpoint.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></em>.<br>
</td>
</tr>
<tr>
<th>
<code>options.mediaType.format</code>
</th>
<td>
String
</td>
<td>
Media type param, such as <code>raw</code>, <code>diff</code>, or <code>text+json</code>. See <ahref="https://developer.github.com/v3/media/">Media Types</a>. Setting <code>options.mediaType.format</code> will amend the <code>headers.accept</code> value.
</td>
</tr>
<tr>
<th>
<code>options.mediaType.previews</code>
</th>
<td>
Array of Strings
</td>
<td>
Name of previews, such as <code>mercy</code>, <code>symmetra</code>, or <code>scarlet-witch</code>. See <ahref="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>.
</td>
</tr>
<tr>
<th>
<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 <code>data</code> parameter"</a> below.
</td>
</tr>
<tr>
<th>
<code>options.request</code>
</th>
<td>
Object
</td>
<td>
Pass custom meta information for the request. The <code>request</code> object will be returned as is.
</td>
</tr>
</tbody>
</table>
All other options will be passed depending on the `method` and `url` options.
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`.
2. If the `method` is `GET` or `HEAD`, the option is passed as a query parameter.
3. Otherwise, the parameter is passed in the request body as a JSON key.
**Result**
`endpoint()` is a synchronous method and returns an object with the following keys:
<table>
<theadalign=left>
<tr>
<th>
key
</th>
<th>
type
</th>
<thwidth=100%>
description
</th>
</tr>
</thead>
<tbodyalign=leftvalign=top>
<tr>
<th><code>method</code></th>
<td>String</td>
<td>The http method. Always lowercase.</td>
</tr>
<tr>
<th><code>url</code></th>
<td>String</td>
<td>The url with placeholders replaced with passed parameters.</td>
</tr>
<tr>
<th><code>headers</code></th>
<td>Object</td>
<td>All header names are lowercased.</td>
</tr>
<tr>
<th><code>body</code></th>
<td>Any</td>
<td>The request body if one is present. Only for <code>PATCH</code>, <code>POST</code>, <code>PUT</code>, <code>DELETE</code> requests.</td>
</tr>
<tr>
<th><code>request</code></th>
<td>Object</td>
<td>Request meta option, it will be returned as it was passed into <code>endpoint()</code></td>
Stateless method to turn endpoint options into request options. Calling
`endpoint(options)` is the same as calling `endpoint.parse(endpoint.merge(options))`.
## Special cases
<aname="data-parameter"></a>
### 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.
```js
const options = endpoint("POST /markdown/raw", {
data: "Hello world github/linguist#1 **cool**, and #1!",
headers: {
accept: "text/html;charset=utf-8",
"content-type": "text/plain",
},
});
// options is
// {
// 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!'
// }
```
### 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).
