Turns REST API endpoints into generic request options
@octokit/endpoint combines GitHub REST API
with your options and turns them into generic request options which you can
then pass into your request library of choice.
@octokit/endopint is meant to run in all JavaScript environments. Browser
builds can be downloaded from each Release.
Minified and gzipped, the build is less than 3kb.
const endpoint = require('@octokit/endpoint')
// Following GitHub docs formatting:
// https://developer.github.com/v3/repos/#list-organization-repositories
const options = endpoint('GET /orgs/:org/repos', {
headers: {
authorization: 'token 0000000000000000000000000000000000000001'
},
org: 'octokit',
type: 'private'
})Alternatively, pass in a method and a url
const options = endpoint({
// route options
method: 'GET',
url: '/orgs/:org/repos',
headers: {
authorization: 'token 0000000000000000000000000000000000000001'
},
// parameters
org: 'octokit',
type: 'private'
})The method returns an object with 3 or 4 keys
| key | type | description |
|---|---|---|
method |
String | The http method. Always lowercase |
url |
String | The url with placeholders replaced with passed parameters |
headers |
Object | All header names are lowercased |
body |
Any | The request body if one is present. Only for PATCH, POST, PUT, DELETE requests |
The above examples shown above return
{
method: 'get',
url: 'https://api.github.com/orgs/octokit/repos?type=private',
headers: {
accept: 'application/vnd.github.v3+json',
authorization: 'token 0000000000000000000000000000000000000001',
'user-agent': 'octokit/endpoint.js v1.2.3'
}
}// using with fetch (https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)
fetch(options.url, ...options)
// using with request (https://github.com/request/request)
request(options)
// using with got (https://github.com/sindresorhus/got)
got[options.method](options.url, options)
// using with axios
axios(options)| name | type | description |
|---|---|---|
baseUrl
|
String |
Required. Any supported http verb, case insensitive. Defaults to https://api.github.com.
|
headers
|
Object |
Custom headers. Passed headers are merged with defaults:headers['user-agent'] defaults to octokit-endpoint.js/1.2.3 (where 1.2.3 is the released version).headers['accept'] defaults to application/vnd.github.v3+json. |
method
|
String |
Required. Any supported http verb, case insensitive. Defaults to Get.
|
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.
|
data
|
Any |
Set request body directly instead of setting it to JSON based on additional parameters. See "The data parameter" below.
|
request
|
Object |
Pass request-related options here, such as [node-fetch extensions options](https://github.com/bitinn/node-fetch#options).
The request object will be returned as is.
|
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.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.
Override or set default options. Example:
const request = require('request')
const myEndpoint = require('@octokit/endpoint').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
})
request(myEndpoint(`GET /orgs/:org/repos`))You can call .defaults() again on the returned method, the defaults will cascade.
const myProjectEndpoint = endpoint.defaults({
baseUrl: 'https://github-enterprise.acme-inc.com/api/v3',
headers: {
'user-agent': 'myApp/1.2.3'
},
org: 'my-project'
})
const myProjectEndpointWithAuth = myProjectEndpoint.defaults({
headers: {
authorization: `token 0000000000000000000000000000000000000001`
}
})myProjectEndpointWithAuth now defaults the baseUrl, headers['user-agent'],
org and headers['authorization'] on top of headers['accept'] that is set
by the global default.
The current default options.
endpoint.DEFAULTS.baseUrl // https://api.github.com
const myEndpoint = endpoint.defaults({
baseUrl: 'https://github-enterprise.acme-inc.com/api/v3'
})
myEndpoint.DEFAULTS.baseUrl // https://github-enterprise.acme-inc.com/api/v3Some 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
endpoint('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!'
})