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).
Install with npm install @octokit/request
.
const octokitRequest = require('@octokit/request')
-
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
// 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.`)
const result = await octokitRequest('POST /graphql', {
headers: {
authorization: 'token 0000000000000000000000000000000000000001'
},
query: `query ($login: String!) {
organization(login: $login) {
repositories(privacy: PRIVATE) {
totalCount
}
}
}`,
variables: {
login: 'octokit'
}
})
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(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.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
|
Object |
Pass node-fetch extensions options, such as agent or timeout . All other `options.request.*` keys will be ignored.
|
All other options will 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.url
ishttps://api.github.com/orgs/foo/repos
- If the
method
isGET
orHEAD
, 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 3 keys
key | type | description |
---|---|---|
headers |
Object | All response headers |
code |
Integer | Response status code |
data |
Any | The response body as returned from server. If the response is JSON then it will be parsed into an object |
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.
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()
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!'
// }
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!'
})