Package Exports

@octokit/request
@octokit/request/lib/http-error
@octokit/request/lib/request

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@octokit/request) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 (node-fetch in Node).

Features
Usage
octokitRequest()
octokitRequest.defaults()
octokitRequest.endpoint
Special cases
- The data parameter – set request body directly
- Set parameters for both the URL/query and the request body
LICENSE

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', {
  headers: {
    accept: 'application/vnd.github.symmetra-preview+json'
  },
  owner: 'ocotkit',
  repo: 'request.js',
  number: 1,
  labels: ['🐛 bug']
})

👍 Sensible defaults

baseUrl: https://api.github.com
headers.accept: application/vnd.github.v3+json
headers.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).

👶 Small bundle size (<5kb minified + gzipped)

Usage

Node

Install with npm install @octokit/request.

const octokitRequest = require('@octokit/request')

Browser

Download octokit-request.min.js from the latest release: https://github.com/octokit/request.js/releases

Load it as script into your web application:

<script src="request-rest.min.js"></script>

The octokitRequest is now available

REST API example

// Following GitHub docs formatting:
// https://developer.github.com/v3/repos/#list-organization-repositories
const result = await octokitRequest('GET /orgs/:org/repos', {
  headers: {
    authorization: 'token 0000000000000000000000000000000000000001'
  },
  org: 'octokit',
  type: 'private'
})

console.log(`${result.data.length} repos found.`)

GraphQL example

const result = await octokitRequest('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 octokitRequest({
  method: 'GET',
  url: '/orgs/:org/repos',
  headers: {
    authorization: 'token 0000000000000000000000000000000000000001'
  },
  org: 'octokit',
  type: 'private'
})

octokitRequest()

octokitRequest(route, options) or octokitRequest(options).

Options

name	type	description
`route`	String	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	Required. Any supported http verb, case insensitive. 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`.
`options.mediaType.format`	String	Media type param, such as `raw`, `html`, or `full`. See Media Types.
`options.mediaType.preview`	Array of strings	Name of previews, such as `mercy`, `symmetra`, or `scarlet-witch`. See API Previews.
`options.method`	String	Required. Any supported http verb, case insensitive. Defaults to `Get`.
`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.agent`	http(s).Agent instance	Node only. Useful for custom proxy, certificate, or dns lookup.
`options.request.fetch`	Function	Custom replacement for built-in fetch method. Useful for testing or request hooks.
`options.request.signal`	new AbortController().signal	Use an `AbortController` instance to cancel a request. In node you can only cancel streamed requests.
`options.request.timeout`	Number	Node only. Request/response timeout in ms, it resets on redirect. 0 to disable (OS limit applies). options.request.signal is recommended instead.

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 returned options.url is https://api.github.com/orgs/foo/repos
If the method is GET or HEAD, the option is passed as query parameter
Otherwise the parameter is passed in the request body as JSON key.

Result

octokitRequest returns a promise and resolves with 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 error instance has additional properties to help with debugging

error.status The http response status code
error.headers The http response headers as an object
error.request The request options such as method, url and data

`octokitRequest.defaults()`

Override or set default options. Example:

const myOctokitRequest = 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
})

myOctokitRequest(`GET /orgs/:org/repos`)

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

const myProjectRequest = octokitRequest.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.

`octokitRequest.endpoint`

See https://github.com/octokit/endpoint.js. Example

const options = octokitRequest.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:

ocotkitRequest.endpoint()
ocotkitRequest.endpoint.defaults()
ocotkitRequest.endpoint.merge()
ocotkitRequest.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 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

octokitRequest('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

@octokit/request