endpoint.js

Turns GitHub REST API endpoints into generic request options

@octokit-next/endpoint combines GitHub REST API routes with parameters and turns them into generic request options that can be used in any request library.

Usage

1<script type="module">
2import { endpoint } from "https://cdn.skypack.dev/@octokit-next/endpoint";
3</script>

1import { endpoint } from "@octokit-next/endpoint";

1import { endpoint } from "https://cdn.skypack.dev/@octokit-next/endpoint?dts";

Example for List organization repositories

1const requestOptions = endpoint("GET /orgs/{org}/repos", {
2  headers: {
3    authorization: "token 0000000000000000000000000000000000000001",
4  },
5  org: "octokit",
6  type: "private",
7});

The resulting requestOptions looks as follows

1{
2  "method": "GET",
3  "url": "https://api.github.com/orgs/octokit/repos?type=private",
4  "headers": {
5    "accept": "application/vnd.github.v3+json",
6    "authorization": "token 0000000000000000000000000000000000000001",
7    "user-agent": "octokit-next/endpoint.js v1.2.3"
8  }
9}

You can pass requestOptions to common request libraries

1const { url, ...options } = requestOptions;
2// https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
3fetch(url, options);
4// https://github.com/sindresorhus/got
5got[options.method](url, options);
6// https://github.com/axios/axios
7axios(requestOptions);

For PUT/POST endpoints with request body parameters, the code is slightly different

1const { url, data, ...options } = requestOptions;
2// https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
3fetch(url, { ...options, body: JSON.stringify(data) });
4// https://github.com/sindresorhus/got
5got[options.method](url, { ...options, json: data });
6// https://github.com/axios/axios
7axios(requestOptions);

API

endpoint(route, options) or endpoint(options)

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:

endpoint.withDefaults()

Override or set default options. Example:

1const myEndpoint = endpoint.withDefaults({
2  baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
3  headers: {
4    "user-agent": "myApp/1.2.3",
5    authorization: `token 0000000000000000000000000000000000000001`,
6  },
7});
8
9const options = myEndpoint(`GET /orgs/{org}/repos`, {
10  org: "my-project",
11  per_page: 100,
12});
13// {
14//   "method": "GET",
15//   "url": "https://api.github.com/orgs/my-project/repos?per_page=100",
16//   "headers": {
17//     "accept": "application/vnd.github.v3+json",
18//     "authorization": "token 0000000000000000000000000000000000000001",
19//     "user-agent": "myApp/1.2.3"
20//   }
21// }

You can call .withDefaults() again on the returned method, the defaults will cascade.

1const myEndpointWithToken2 = myEndpoint.withDefaults({
2  headers: {
3    authorization: `token 0000000000000000000000000000000000000002`,
4  },
5});
6
7const options2 = myEndpointWithToken2(`GET /orgs/{org}/repos`, {
8  org: "my-project",
9  per_page: 100,
10});
11// {
12//   "method": "GET",
13//   "url": "https://api.github.com/orgs/my-project/repos?per_page=100",
14//   "headers": {
15//     "accept": "application/vnd.github.v3+json",
16//     "authorization": "token 0000000000000000000000000000000000000002",
17//     "user-agent": "myApp/1.2.3"
18//   }
19// }

endpoint.DEFAULTS

The current default options.

1endpoint.DEFAULTS.baseUrl; // https://api.github.com
2const myEndpoint = endpoint.withDefaults({
3  baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
4});
5myEndpoint.DEFAULTS.baseUrl; // https://github-enterprise.acme-inc.com/api/v3

endpoint.merge(route, options) or endpoint.merge(options)

Get the defaulted endpoint options, but without parsing them into request options:

1const myProjectEndpoint = endpoint.withDefaults({
2  baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
3  headers: {
4    "user-agent": "myApp/1.2.3",
5  },
6  org: "my-project",
7});
8myProjectEndpoint.merge("GET /orgs/{org}/repos", {
9  headers: {
10    authorization: `token 0000000000000000000000000000000000000001`,
11  },
12  org: "my-secret-project",
13  type: "private",
14});
15
16// {
17//   baseUrl: 'https://github-enterprise.acme-inc.com/api/v3',
18//   method: 'GET',
19//   url: '/orgs/{org}/repos',
20//   headers: {
21//     accept: 'application/vnd.github.v3+json',
22//     authorization: `token 0000000000000000000000000000000000000001`,
23//     'user-agent': 'myApp/1.2.3'
24//   },
25//   org: 'my-secret-project',
26//   type: 'private'
27// }

endpoint.parse()

Stateless method to turn endpoint options into request options. Calling endpoint(options) is the same as calling endpoint.parse(endpoint.merge(options)).

Types

@octokit-next/endpoint supports types for all REST API endpoints across all supported targets (github.com, GitHub AE, GitHub Enterprise Server).

In order to take advantage of the types, you have to install the @octokit-next/types-rest-api* packages for the platform(s) you want to target.

For example, to get types for all of github.com's REST API endpoints, use @octokit-next/types-rest-api.

1/// <reference types="@octokit-next/types-rest-api" />
2
3import { endpoint } from "@octokit-next/endpoint";
4
5endpoint("");
6// Set cursor in the route argument and press `Ctrl + Space` to get a type ahead for all 700+ REST API endpoints
7
8const requestOptions = endpoint("GET /orgs/{org}/repos", { org: "octokit" });
9// requestOptions.method is now typed as `"GET"` instead of `string`
10// requestOptions.url is now typed as `"/orgs/{org}/repos"` instead of `string`
11// requestOptions.data does not exist on types.

To support GitHub Enterprise Server 3.0 and all new versions, import @octokit-next/types-rest-api-ghes-3.0 and set the request version:

1/// <reference types="@octokit-next/types-rest-api-ghes-3.0" />
2
3import { endpoint } from "@octokit-next/endpoint";
4
5endpoint("", {
6  request: {
7    version: "ghes-3.0",
8  },
9});
10// Set cursor in the route argument and press `Ctrl + Space` to get a type ahead for all GHES 3.0 REST API endpoints
11
12const requestOptions = endpoint("GET /admin/users/{username}", {
13  request: {
14    version: "ghes-3.0",
15  },
16  username: "octocat",
17});
18// requestOptions.method is now typed as `"GET"` instead of `string`
19// requestOptions.url is now typed as `"/admin/users/{username}"` instead of `string`
20// requestOptions.data does not exist on types.

Types in the @octokit-next/types-rest-api-ghes packages are additive. So you can set request.version to ghes-3.1 and ghes-3.2 as well.

The version can be set using endpoint.withDefaults() as well. You can override the version in each endpoint() call.

1/// <reference types="@octokit-next/types-rest-api-ghes-3.0" />
2
3import { endpoint } from "@octokit-next/endpoint";
4
5const ghes30endpoint = endpoint.withDefaults({
6  request: {
7    version: "ghes-3.0",
8  },
9});
10
11endpoint("");
12// Set cursor in the route argument and press `Ctrl + Space` to get a type ahead for all GHES 3.0 REST API endpoints

If you need your script to work across github.com and a minimal GitHub Enterprise Server version, you can use any of the @octokit-next/types-rest-api-ghes-*-compatible packages.

1/// <reference types="@octokit-next/types-rest-api-ghes-3.0-compatible" />
2
3import { endpoint } from "@octokit-next/endpoint";
4
5const ghes30endpoint = endpoint.withDefaults({
6  request: {
7    version: "ghes-3.0",
8  },
9});
10
11endpoint("");
12// Set cursor in the route argument and press `Ctrl + Space` to get a type ahead for all REST API endpoints
13// that exist in both github.com and GitHub Enterprise Server 3.0

Special cases

The data parameter – set request body directly

Some endpoints such as 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.

1const options = endpoint("POST /markdown/raw", {
2  data: "Hello world github/linguist#1 **cool**, and #1!",
3  headers: {
4    accept: "text/html;charset=utf-8",
5    "content-type": "text/plain",
6  },
7});
8
9// options is
10// {
11//   method: 'post',
12//   url: 'https://api.github.com/markdown/raw',
13//   headers: {
14//     accept: 'text/html;charset=utf-8',
15//     'content-type': 'text/plain',
16//     'user-agent': userAgent
17//   },
18//   body: 'Hello world github/linguist#1 **cool**, and #1!'
19// }

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.

Example

1endpoint(
2  "POST https://uploads.github.com/repos/octocat/Hello-World/releases/1/assets{?name,label}",
3  {
4    name: "example.zip",
5    label: "short description",
6    headers: {
7      "content-type": "text/plain",
8      "content-length": 14,
9      authorization: `token 0000000000000000000000000000000000000001`,
10    },
11    data: "Hello, world!",
12  }
13);

LICENSE

MIT