request.js
Send parameterized requests to GitHub’s APIs with sensible defaults in browsers and Node
@octokit/request is a request library for browsers & node that makes it easier
to interact with GitHub’s REST API and
GitHub’s GraphQL API.
It uses @octokit/endpoint to parse
the passed options and sends the request using fetch. You can pass a custom fetch function using the options.request.fetch option, see below.
- request.js
Features
🤩 1:1 mapping of REST API endpoint documentation, e.g. Add labels to an issue becomes
request("POST /repos/{owner}/{repo}/issues/{number}/labels", {
mediaType: {
previews: ["symmetra"],
},
owner: "octokit",
repo: "request.js",
number: 1,
labels: ["🐛 bug"],
});👶 Small bundle size (<4kb minified + gzipped)
😎 Authenticate with any of GitHubs Authentication Strategies.
👍 Sensible defaults
baseUrl:https://api.github.comheaders.accept:application/vnd.github.v3+jsonheaders['user-agent']:octokit-request.js/<current version> <OS information>, e.g.octokit-request.js/1.2.3 Node.js/10.15.0 (macOS Mojave; x64)
👌 Simple to test: mock requests by passing a custom fetch method.
🧐 Simple to debug: Sets error.request to request options causing the error (with redacted credentials).
Usage
| Browsers |
Load @octokit/request directly from esm.sh
<script type="module">
import { request } from "https://esm.sh/@octokit/request";
</script> |
|---|---|
| Node |
Install with const { request } = require("@octokit/request");
// or: import { request } from "@octokit/request"; |
REST API example
// Following GitHub docs formatting:
// https://developer.github.com/v3/repos/#list-organization-repositories
const result = await request("GET /orgs/{org}/repos", {
headers: {
authorization: "token 0000000000000000000000000000000000000001",
},
org: "octokit",
type: "private",
});
console.log(`${result.data.length} repos found.`);GraphQL example
For GraphQL request we recommend using @octokit/graphql
const result = await request("POST /graphql", {
headers: {
authorization: "token 0000000000000000000000000000000000000001",
},
query: `query ($login: String!) {
organization(login: $login) {
repositories(privacy: PRIVATE) {
totalCount
}
}
}`,
variables: {
login: "octokit",
},
});Alternative: pass method & url as part of options
Alternatively, pass in a method and a url
const result = await request({
method: "GET",
url: "/orgs/{org}/repos",
headers: {
authorization: "token 0000000000000000000000000000000000000001",
},
org: "octokit",
type: "private",
});Authentication
The simplest way to authenticate a request is to set the Authorization header directly, e.g. to a personal access token.
const requestWithAuth = request.defaults({
headers: {
authorization: "token 0000000000000000000000000000000000000001",
},
});
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.
const { createAppAuth } = require("@octokit/auth-app");
const auth = createAppAuth({
appId: process.env.APP_ID,
privateKey: process.env.PRIVATE_KEY,
installationId: 123,
});
const requestWithAuth = request.defaults({
request: {
hook: auth.hook,
},
mediaType: {
previews: ["machine-man"],
},
});
const { data: app } = await requestWithAuth("GET /app");
const { data: app } = await requestWithAuth(
"POST /repos/{owner}/{repo}/issues",
{
owner: "octocat",
repo: "hello-world",
title: "Hello from the engine room",
},
);request()
request(route, options) or request(options).
Options
| name | type | description |
|---|---|---|
route
|
String |
**Required**. If route is set it has to be a string consisting of the request method and URL, e.g. GET /orgs/{org}
|
options.baseUrl
|
String |
The base URL that route or url will be prefixed with, if they use relative paths. Defaults to https://api.github.com.
|
options.headers
|
Object |
Custom headers. Passed headers are merged with defaults:headers['user-agent'] defaults to octokit-rest.js/1.2.3 (where 1.2.3 is the released version).headers['accept'] defaults to application/vnd.github.v3+json.Use options.mediaType.{format,previews} to request API previews and custom media types.
|
options.method
|
String |
Any supported http verb, case insensitive. Defaults to Get.
|
options.mediaType.format
|
String | Media type param, such as `raw`, `html`, or `full`. See Media Types. |
options.mediaType.previews
|
Array of strings | Name of previews, such as `mercy`, `symmetra`, or `scarlet-witch`. See GraphQL Schema Previews. Note that these only apply to GraphQL requests and have no effect on REST routes. |
options.url
|
String |
**Required**. 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.data
|
Any | Set request body directly instead of setting it to JSON based on additional parameters. See "The `data` parameter" below. |
options.request.fetch
|
Function | Custom replacement for fetch. Useful for testing or request hooks. |
options.request.hook
|
Function |
Function with the signature hook(request, endpointOptions), where endpointOptions are the parsed options as returned by endpoint.merge(), and request is request(). This option works great in conjuction with before-after-hook.
|
options.request.signal
|
new AbortController().signal |
Use an AbortController instance to cancel a request. In node you can only cancel streamed requests.
|
options.request.log
|
object
|
Used for internal logging. Defaults to console.
|
options.request.parseSuccessResponseBody
|
boolean
|
If set to false the returned `response` will be passed through from `fetch`. This is useful to stream response.body when downloading files from the GitHub API.
|
All other options except options.request.* will be passed depending on the method and url options.
- 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 returnedoptions.urlishttps://api.github.com/orgs/foo/repos - If the
methodisGETorHEAD, the option is passed as query parameter - Otherwise the parameter is passed in the request body as JSON key.
Result
request returns a promise. If the request was successful, the promise resolves with an object containing 4 keys:
| key | type | description |
|---|---|---|
status |
Integer | Response status status |
url |
String | URL of response. If a request results in redirects, this is the final URL. You can send a HEAD request to retrieve it without loading the full response body. |
headers |
Object | All response headers |
data |
Any | The response body as returned from server. If the response is JSON then it will be parsed into an object |
If an error occurs, the promise is rejected with an error object containing 3 keys to help with debugging:
error.statusThe http response status codeerror.requestThe request options such asmethod,urlanddataerror.responseThe http response object withurl,headers, anddata
If the error is due to an AbortSignal being used, the resulting AbortError is bubbled up to the caller.
request.defaults()
Override or set default options. Example:
const myrequest = require("@octokit/request").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,
});
myrequest(`GET /orgs/{org}/repos`);You can call .defaults() again on the returned method, the defaults will cascade.
const myProjectRequest = request.defaults({
baseUrl: "https://github-enterprise.acme-inc.com/api/v3",
headers: {
"user-agent": "myApp/1.2.3",
},
org: "my-project",
});
const myProjectRequestWithAuth = myProjectRequest.defaults({
headers: {
authorization: `token 0000000000000000000000000000000000000001`,
},
});myProjectRequest now defaults the baseUrl, headers['user-agent'],
org and headers['authorization'] on top of headers['accept'] that is set
by the global default.
request.endpoint
See https://github.com/octokit/endpoint.js. Example
const options = request.endpoint("GET /orgs/{org}/repos", {
org: "my-project",
type: "private",
});
// {
// method: 'GET',
// url: 'https://api.github.com/orgs/my-project/repos?type=private',
// headers: {
// accept: 'application/vnd.github.v3+json',
// authorization: 'token 0000000000000000000000000000000000000001',
// 'user-agent': 'octokit/endpoint.js v1.2.3'
// }
// }All of the @octokit/endpoint API can be used:
octokitRequest.endpoint()octokitRequest.endpoint.defaults()octokitRequest.endpoint.merge()octokitRequest.endpoint.parse()
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 response = await request("POST /markdown/raw", {
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.
Example
request(
"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!",
},
);Set a custom Agent to your requests
The way to pass a custom Agent to requests is by creating a custom fetch function and pass it as options.request.fetch. A good example can be undici's fetch implementation.
Example (See example in CodeSandbox)
import { request } from "@octokit/request";
import { fetch as undiciFetch, Agent } from "undici";
/** @type {typeof import("undici").fetch} */
const myFetch = (url, options) => {
return undiciFetch(url, {
...options,
dispatcher: new Agent({
keepAliveTimeout: 10,
keepAliveMaxTimeout: 10,
}),
});
};
const { data } = await request("GET /users/{username}", {
username: "octocat",
headers: {
"X-GitHub-Api-Version": "2022-11-28",
},
options: {
request: {
fetch: myFetch,
},
},
});
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
![greenkeeper[bot] avatar](https://avatars.githubusercontent.com/in/505?v=4 "greenkeeper[bot]")
![renovate[bot] avatar](https://avatars.githubusercontent.com/in/2740?v=4 "renovate[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent