HOW_IT_WORKS.md

back to @octokit/rest

How it works

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.