Skip to content
Turns REST API endpoints into generic request options
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib fix: previews with `.github` prefix in accept header Mar 14, 2019
test test: previews with `.github` prefix in accept header Mar 14, 2019
.gitignore build(gitignore): dist/ Oct 20, 2018
.travis.yml
CODE_OF_CONDUCT.md docs(CODE_OF_CONDUCT): Contributor Covenant Oct 21, 2018
LICENSE docs(LICENSE): MIT Oct 20, 2018
README.md
cypress.json
index.js feat: repeated .defaults() Oct 20, 2018
package-lock.json chore(package): update lockfile package-lock.json Feb 26, 2019
package.json
with-defaults.js refactor: endpoint.options() is now endpoint.merge() Oct 31, 2018

README.md

endpoint.js

Turns REST API endpoints into generic request options

@latest Build Status Coverage Status Greenkeeper

@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/endpoint 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.

Usage

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'
})

// {
//   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'
//   }
// }

Alternatively, pass in all options in a single object:

const options = endpoint({ method, url, headers, org, type })

Using @octokit/endpoint with common request libraries:

// 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)

API

endpoint()

endpoint(route, options) or endpoint(options).

Options

name type description
route String If set, it has to be a string consisting of URL and the request method, e.g., GET /orgs/:org. If it’s set to a URL, only the method defaults to GET.
options.baseUrl String Defaults to https://api.github.com.
options.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.
options.mediaType.format String Media type param, such as raw, diff, or text+json. See Media Types. Setting options.mediaType.format will amend the headers.accept value.
options.mediaType.previews Array of Strings Name of previews, such as mercy, symmetra, or scarlet-witch. See API Previews. If options.mediaType.previews was set as default, the new previews will be merged into the default ones. Setting options.mediaType.previews will amend the headers.accept value. options.mediaType.previews will be merged with an existing array set using .defaults().
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 custom meta information for the request. The request object will be returned as is.

All other options will be passed depending on the method and url options.

  1. If the option key has a placeholder in the url, it will be used as the 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.
  2. If the method is GET or HEAD, the option is passed as a query parameter.
  3. Otherwise, the parameter is passed in the request body as a JSON key.

Result

endpoint() is a synchronous method and returns an object with the following 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.

endpoint.defaults()

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.

endpoint.DEFAULTS

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/v3

endpoint.merge()

Get the defaulted endpoint options, but without parsing them into request options:

const myProjectEndpoint = endpoint.defaults({
  baseUrl: 'https://github-enterprise.acme-inc.com/api/v3',
  headers: {
    'user-agent': 'myApp/1.2.3'
  },
  org: 'my-project'
})
myProjectEndpoint.merge('GET /orgs/:org/repos', {
  headers: {
    authorization: `token 0000000000000000000000000000000000000001`
  },
  org: 'my-secret-project',
  type: 'private'
})
// {
//   baseUrl: 'https://github-enterprise.acme-inc.com/api/v3',
//   method: 'GET',
//   url: '/orgs/:org/repos',
//   headers: {
//     accept: 'application/vnd.github.v3+json',
//     authorization: `token 0000000000000000000000000000000000000001`,
//     'user-agent': 'myApp/1.2.3'
//   },
//   org: 'my-secret-project',
//   type: 'private'
// }

endpoint.parse()

Stateless method to turn endpoint options into request options. Calling endpoint(options) is the same as calling endpoint.parse(endpoint.merge(options)).

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

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!'
})

LICENSE

MIT

You can’t perform that action at this time.