octokit/request.jsPublic

NotificationsYou must be signed in to change notification settings
Fork71
Star254

Send parameterized requests to GitHub’s APIs with sensible defaults in browsers and Node

License

MIT license

254 stars 71 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 748 Commits
.github		.github
scripts		scripts
src		src
test		test
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vite.config.js		vite.config.js

Repository files navigation

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 easierto interact withGitHub’s REST API andGitHub’s GraphQL API.

It uses@octokit/endpoint to parsethe passed options and sends the request usingfetch. You can pass a customfetch function using theoptions.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 ofGitHubs Authentication Strategies.

👍 Sensible defaults

baseUrl:https://api.github.com
headers.accept:application/vnd.github.v3+json
headers['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: Setserror.request to request options causing the error (with redacted credentials).

Usage

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

REST API example

// Following GitHub docs formatting:// https://developer.github.com/v3/repos/#list-organization-repositoriesconstresult=awaitrequest("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

constresult=awaitrequest("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

constresult=awaitrequest({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 theAuthorization header directly, e.g. to apersonal access token.

constrequestWithAuth=request.defaults({headers:{authorization:"token 0000000000000000000000000000000000000001",},});constresult=awaitrequestWithAuth("GET /user");

For more complex authentication strategies such as GitHub Apps or Basic, we recommend the according authentication library exported by@octokit/auth.

import{createAppAuth}from"@octokit/auth-app";constauth=createAppAuth({appId:process.env.APP_ID,privateKey:process.env.PRIVATE_KEY,installationId:123,});constrequestWithAuth=request.defaults({request:{hook:auth.hook,},mediaType:{previews:["machine-man"],},});const{data:app}=awaitrequestWithAuth("GET /app");const{data:app}=awaitrequestWithAuth("POST /repos/{owner}/{repo}/issues",{owner:"octocat",repo:"hello-world",title:"Hello from the engine room",},);

request()

request(route, options) orrequest(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 supportedhttp verb, case-insensitive.Defaults to`Get`.
`options.mediaType.format`	String	Media type param, such as `raw`, `html`, or `full`. SeeMedia Types.
`options.mediaType.previews`	Array of strings	Name of previews, such as `mercy`, `symmetra`, or `scarlet-witch`. SeeGraphQL 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 usingurl-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 forfetch. 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 conjunction withbefore-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 exceptoptions.request.* will be passed depending on themethod andurl options.

If the option key is a placeholder in theurl, it will be used as replacement. For example, if the passed options are{url: '/orgs/{org}/repos', org: 'foo'} the returnedoptions.url ishttps://api.github.com/orgs/foo/repos
If themethod isGET orHEAD, 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 anerror object containing 3 keys to help with debugging:

error.status The http response status code
error.request The request options such asmethod,url anddata
error.response The http response object withurl,headers, anddata

If the error is due to anAbortSignal being used, the resultingAbortError is bubbled up to the caller.

`request.defaults()`

Override or set default options. Example:

import{request}from"@octokit/request";constmyrequest=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.

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

myProjectRequest now defaults thebaseUrl,headers['user-agent'],org andheaders['authorization'] on top ofheaders['accept'] that is setby the global default.

`request.endpoint`

Seehttps://github.com/octokit/endpoint.js. Example

constoptions=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:

Special cases

The`data` parameter – set request body directly

Some endpoints such asRender 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 thedata parameter.

constresponse=awaitrequest("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 tooptions.url, as defined in theRFC 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 customAgent to requests is by creating a customfetch function and pass it asoptions.request.fetch. A good example can beundici'sfetch implementation.

Example (See example in CodeSandbox)

import{request}from"@octokit/request";import{fetchasundiciFetch,Agent}from"undici";/**@type {typeof import("undici").fetch} */constmyFetch=(url,options)=>{returnundiciFetch(url,{    ...options,dispatcher:newAgent({keepAliveTimeout:10,keepAliveMaxTimeout:10,}),});};const{ data}=awaitrequest("GET /users/{username}",{username:"octocat",headers:{"X-GitHub-Api-Version":"2022-11-28",},options:{request:{fetch:myFetch,},},});