Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
2 contributors

Users who have contributed to this file

@gr2m @zaki-yama
136 lines (110 sloc) 5.02 KB

back to @octokit/rest

How it works

lifecycle

  1. Endpoint options ① - ④
  2. Transform endpoint to request options ⑥ - ⑦
  3. Sending a request & receiving a response ⑧ & ⑩
  4. Hooks ⑤ & ⑨

Endpoint options (① - ④)

@octokit/rest exposes a method for each REST API endpoint, for example octokit.repos.listForOrg() for GET /orgs/:org/repos. The methods are generated from the plugins/rest-api-endpoints/routes.json file which defines the ② endpoint default options method, url and in some cases headers.

② endpoint default options are merged with ① global defaults, which are based on @octokit/endpoint/lib/defaults.js and the options that were passed into the require('@octokit/rest')(options) client setup.

Both are merged with ③ user options passed into the method. Altogether they result in ④ endpoint options.

Example: get all public repositories of the the @octokit GitHub organization.

octokit.repos.listForOrg({ org: 'octokit', type: 'public' })

④ endpoint options will be

Option Value Source
baseUrl 'https://api.github.com' ① global defaults
user-agent (header) 'octokit/rest.js v1.0.0' ① global defaults
accept (header) 'application/vnd.github.v3+json' ① global defaults
method 'GET' ② endpoint defaults
url '/orgs/:org/repos' ② endpoint defaults
org (URL variable) 'octokit' ③ user options
type (endpoint parameter) 'public' ③ user options

Transform endpoint to request options (⑥ - ⑦)

④ Endpoint options are ⑥ transformed into ⑦ request options using @octokit/endpoint.

For example, the endpoint options shown above would result in

method 'GET'
url 'https://api.github.com/orgs/octokit/repos?type=public'
headers[user-agent] 'octokit/rest.js v1.0.0'
headers[accept] 'application/vnd.github.v3+json'

Sending a request & receiving a response ⑧ & ⑩

Using ⑦ request options a ⑧ request is sent to the GitHub REST API. The ⑩ response is returned to the user.

Requests are sent using @octokit/request. It's using the native fetch method in the browsers and node-fetch in other environments.

Hooks ⑤ & ⑨

Hooks are used to inject functionality like authentication. For example, the internal authentication plugin is registering a request hook in plugins/authentication/index.js. The method sets the authorization header based on the auth option passed to the Octokit constructor.

Hooks can be registered using octokit.hook.{before|after|error|wrap}:

octokit.hook.before('request', async (options) => {
  validate(options)
})
octokit.hook.after('request', async (response, options) => {
  console.log(`${options.method} ${options.url}: ${response.status}`)
})
octokit.hook.error('request', async (error, options) => {
  if (error.status === 304) {
    return findInCache(error.headers.etag)
  }

  throw error
})
octokit.hook.wrap('request', async (request, options) => {})

The methods can return a Promise for asynchronous execution. options can be changed in the octokit.hook.before callback before they are transformed ⑥ transformed. The ⑩ response can be changed in the octokit.hook.after callback before it is returned to the user. octokit.hook.wrap allows to do both, or replace the original request method altogether with a custom request method.

See before-after-hook for more details.

You can’t perform that action at this time.