request.js

@octokit/request is the low-level HTTP client at the core of Octokit.js, providing a thin, fetch-based wrapper for calling GitHub’s REST and GraphQL APIs. It maps API routes directly to method-and-path strings like GET /orgs/{org}/repos, parses URL templates, merges sensible defaults (base URL, user-agent, media type headers), and returns a normalized response object with status, url, headers, and parsed data.

Built on @octokit/endpoint for route parsing and merging, and using the platform’s native fetch (or a caller-supplied replacement) instead of a bundled HTTP client, the library stays small (under 4kb minified and gzipped) while remaining fully testable — requests can be intercepted by swapping the fetch implementation. It underpins the wider Octokit ecosystem (Octokit.js, REST.js, GraphQL.js) but is equally usable standalone by anyone who wants a low-ceremony way to talk to GitHub’s APIs from Node or the browser.

What You Get

• Route-string API mirroring GitHub’s REST docs (METHOD /path/{placeholder}) so endpoint calls read like the documentation
• Built-in defaults for baseUrl, user-agent, and Accept headers, overridable via .defaults()
• Support for GitHub’s GraphQL endpoint via the same request function
• Pluggable fetch implementation for testing, custom agents, or non-standard runtimes
• Normalized error handling via @octokit/request-error, exposing status, request, and response on thrown errors

Common Use Cases

• Building a custom GitHub integration without pulling in the full Octokit SDK
• Powering authenticated requests for a GitHub App or OAuth app via a request.hook
• Writing internal tooling and scripts that call GitHub’s REST or GraphQL API directly
• Testing GitHub API interactions by swapping in a mock fetch implementation
• Streaming or downloading binary GitHub API responses (release assets, archives) via parseSuccessResponseBody: false

Under The Hood

Architecture The library is a small, cleanly layered module: index.ts wires @octokit/endpoint’s endpoint object together with defaults.ts (a single object literal supplying the default user-agent header) through with-defaults.ts, which wraps endpoint.defaults/merge/parse into a callable request function that also exposes .endpoint and .defaults for cascading configuration. Actual network I/O is isolated in fetch-wrapper.ts, which normalizes fetch responses and errors into either an OctokitResponse or a thrown RequestError. This separates endpoint-parsing (delegated to @octokit/endpoint), option-merging and hook-dispatch (with-defaults.ts), and transport (fetch-wrapper.ts) into distinct concerns — swapping the core abstraction, fetch itself, is a first-class supported operation since it is threaded explicitly through options.request.fetch rather than assumed to be global.

Tech Stack Written in TypeScript (98% of the codebase) targeting Node >=20 and browsers, built via a custom scripts/build.mjs plus tsc, and tested with vitest and @vitest/coverage-v8 using fetch-mock and undici for fetch mocking. It depends on @octokit/endpoint for route templating, @octokit/request-error for typed errors, content-type and json-with-bigint for response body parsing, and universal-user-agent for cross-platform UA strings. The package ships ESM-only (type: module), formats with Prettier (no ESLint), and automates releases with semantic-release.

Code Quality The test suite is extensive relative to the library’s size — over 3,100 lines across request.test.ts, request-native-fetch.test.ts, defaults.test.ts, is-plain-object.test.ts, and request-no-global-fetch.test.ts — covering both the legacy and native-fetch code paths against a local mock HTTP server and fetch-mock. Errors are explicit and typed (RequestError carries status, request, and response context rather than being swallowed), naming is consistent across a small, well-scoped file surface, and typing throughout leans on @octokit/types. CI runs on GitHub Actions and pretest enforces Prettier formatting on every run.

API Design The defining ergonomic choice is a 1:1 mapping between GitHub’s own REST documentation and call syntax — request("POST /repos/{owner}/{repo}/issues/{number}/labels", {...}) mirrors the docs verbatim, minimizing the translation step between reading the API reference and writing code. Defaults cascade via .defaults() so consumers or auth libraries can layer headers and base URLs without re-specifying earlier options, and the request.hook extension point lets authentication strategies (GitHub Apps, OAuth) inject behavior without forking the request function. Getting started requires no configuration beyond a route string, while options.request.fetch provides an escape hatch for custom agents or streaming responses.