@octokit/endpoint

What is @octokit/endpoint?

The @octokit/endpoint npm package is designed to convert GitHub API endpoint options into the URL and headers format that the GitHub REST API expects. It's part of the Octokit suite of libraries which are used to interact with the GitHub API in a more convenient and structured way. This package is particularly useful for developers who need to make custom requests to the GitHub API beyond what higher-level Octokit libraries provide, allowing for detailed control over the request parameters and headers.

What are @octokit/endpoint's main functionalities?

Creating a custom GitHub REST API endpoint

This code sample demonstrates how to create a custom endpoint for fetching issues from a GitHub repository. You specify the HTTP method, the URL pattern, and any necessary headers. The `owner` and `repo` parameters are used to fill in the URL pattern.

{
  "method": "GET",
  "url": "/repos/{owner}/{repo}/issues",
  "headers": {
    "accept": "application/vnd.github.v3+json"
  },
  "owner": "octokit",
  "repo": "endpoint.js"
}

Converting endpoint options to request URL and headers

This example shows how to use the @octokit/endpoint package to convert endpoint options into a format that can be used to make an HTTP request. It includes the method, URL, headers, and other parameters like `title` for the body of the request.

const { endpoint } = require('@octokit/endpoint');
const options = endpoint({
  method: 'POST',
  url: '/repos/{owner}/{repo}/issues',
  headers: {
    accept: 'application/vnd.github.v3+json'
  },
  owner: 'octokit',
  repo: 'endpoint.js',
  title: 'New issue title'
});
console.log(options); // Logs the URL and headers object ready for the request

Other packages similar to @octokit/endpoint

node-fetch

node-fetch is a lightweight module that brings window.fetch to Node.js. While it doesn't directly offer GitHub API endpoint conversion like @octokit/endpoint, it's commonly used for making HTTP requests to APIs, including GitHub's REST API. Developers can manually construct their requests to GitHub or any other service.

axios

Axios is a promise-based HTTP client for the browser and Node.js. Similar to node-fetch, it allows for making HTTP requests to REST APIs, including GitHub's. It provides more features out of the box compared to node-fetch, such as automatic JSON data transformation and request and response interception. However, like node-fetch, it requires manual setup for calling GitHub API endpoints.

README

endpoint.js

Turns GitHub REST API endpoints into generic request options

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

• Usage
• API
  • endpoint(route, options) or endpoint(options)
  • endpoint.defaults()
  • endpoint.DEFAULTS
  • endpoint.merge(route, options) or endpoint.merge(options)
  • endpoint.parse()
• Special cases
  • The data parameter – set request body directly
  • Set parameters for both the URL/query and the request body
• LICENSE

Usage

Browsers	Load @octokit/endpoint directly from esm.sh <script type="module"> import { endpoint } from "https://esm.sh/@octokit/endpoint"; </script>
Node	Install with npm install @octokit/endpoint import { endpoint } from "@octokit/endpoint";

Example for List organization repositories

const requestOptions = endpoint("GET /orgs/{org}/repos", {
  headers: {
    authorization: "token 0000000000000000000000000000000000000001",
  },
  org: "octokit",
  type: "private",
});

The resulting requestOptions looks as follows

{
  "method": "GET",
  "url": "https://api.github.com/orgs/octokit/repos?type=private",
  "headers": {
    "accept": "application/vnd.github.v3+json",
    "authorization": "token 0000000000000000000000000000000000000001",
    "user-agent": "octokit/endpoint.js v1.2.3"
  }
}

You can pass requestOptions to common request libraries

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);

[!IMPORTANT] As we use conditional exports, you will need to adapt your tsconfig.json. See the TypeScript docs on package.json "exports".

API

endpoint(route, options) or endpoint(options)

name	type	description
route	String	If set, it has to be a string consisting of URL and the request method, e.g., GET /orgs/{org}. If it’s set to a URL, only the method defaults to GET.
options.method	String	Required unless route is set. Any supported http verb. Defaults to GET.
options.url	String	Required unless route is set. A path or full URL which may contain :variable or {variable} placeholders, e.g., /orgs/{org}/repos. The url is parsed using url-template.
options.baseUrl	String	Defaults to https://api.github.com.
options.headers	Object	Custom headers. Passed headers are merged with defaults: headers['user-agent'] defaults to octokit-endpoint.js/1.2.3 (where 1.2.3 is the released version). headers['accept'] defaults to application/vnd.github.v3+json.
options.mediaType.format	String	Media type param, such as raw, diff, or text+json. See Media Types. Setting options.mediaType.format will amend the headers.accept value.
options.data	Any	Set request body directly instead of setting it to JSON based on additional parameters. See "The data parameter" below.
options.request	Object	Pass custom meta information for the request. The request object will be returned as is.

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:

key	type	description
method	String	The http method. Always lowercase.
url	String	The url with placeholders replaced with passed parameters.
headers	Object	All header names are lowercased.
body	Any	The request body if one is present. Only for PATCH, POST, PUT, DELETE requests.
request	Object	Request meta option, it will be returned as it was passed into endpoint()

endpoint.defaults()

Override or set default options. Example:

const request = require("request");
const myEndpoint = require("@octokit/endpoint").defaults({
  baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
  headers: {
    "user-agent": "myApp/1.2.3",
    authorization: `token 0000000000000000000000000000000000000001`,
  },
  org: "my-project",
  per_page: 100,
});

request(myEndpoint(`GET /orgs/{org}/repos`));

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

const myProjectEndpoint = endpoint.defaults({
  baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
  headers: {
    "user-agent": "myApp/1.2.3",
  },
  org: "my-project",
});
const myProjectEndpointWithAuth = myProjectEndpoint.defaults({
  headers: {
    authorization: `token 0000000000000000000000000000000000000001`,
  },
});

myProjectEndpointWithAuth now defaults the baseUrl, headers['user-agent'], org and headers['authorization'] on top of headers['accept'] that is set by the global default.

endpoint.DEFAULTS

The current default options.

endpoint.DEFAULTS.baseUrl; // https://api.github.com
const myEndpoint = endpoint.defaults({
  baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
});
myEndpoint.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:

const myProjectEndpoint = endpoint.defaults({
  baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
  headers: {
    "user-agent": "myApp/1.2.3",
  },
  org: "my-project",
});
myProjectEndpoint.merge("GET /orgs/{org}/repos", {
  headers: {
    authorization: `token 0000000000000000000000000000000000000001`,
  },
  org: "my-secret-project",
  type: "private",
});

// {
//   baseUrl: 'https://github-enterprise.acme-inc.com/api/v3',
//   method: 'GET',
//   url: '/orgs/{org}/repos',
//   headers: {
//     accept: 'application/vnd.github.v3+json',
//     authorization: `token 0000000000000000000000000000000000000001`,
//     'user-agent': 'myApp/1.2.3'
//   },
//   org: 'my-secret-project',
//   type: 'private'
// }

endpoint.parse()

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

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.

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.

Example

endpoint(
  "POST https://uploads.github.com/repos/octocat/Hello-World/releases/1/assets{?name,label}",
  {
    name: "example.zip",
    label: "short description",
    headers: {
      "content-type": "text/plain",
      "content-length": 14,
      authorization: `token 0000000000000000000000000000000000000001`,
    },
    data: "Hello, world!",
  },
);

LICENSE

MIT