Package Exports

@octokit/endpoint

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/endpoint) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

endpoint.js

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. The bundle size is currently 9.15KB (minified and gzipped). [Help us reduce the bundle size](Reduce bundle size for browsers) 🙏

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

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 `@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)

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.

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 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 as request body.

endpoint.defaults()

Override or set default options. Example:

const request = require('request')
const myEndpoint = require('@octokit/endpoint').defaults({
  baseUrl: 'http://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: 'http://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.

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

@octokit/endpoint