- Endpoint options ① - ④
- Transform endpoint to request options ⑥ - ⑦
- Sending a request & receiving a response ⑧ & ⑩
- Hooks ⑤ & ⑨
@octokit/rest exposes a method for each REST API endpoint, for example github.repos.getForOrg() for GET /orgs/:org/repos. The methods are generated from the lib/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 lib/endpoint/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.
github.repos.getForOrg({ org: 'octokit', type: 'public' })④ endpoint options will be
| Option | Value | Source |
|---|---|---|
| baseUrl | 'https://api.github.com' |
① endpoint 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 |
④ Endpoint options are ⑥ transformed into ⑦ request options. Most of the transform is happening in lib/endpoint/index.js.
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' |
Using ⑦ request options a ⑧ request is sent to the GitHub REST API. The ⑩ response is returned to the user.
Most of the request/response is happening in lib/request/request.js. It is currently using Node’s native http & https modules, but we will probably use a fetch polyfill in future for better browser compatibility & smaller bundle size.
Hooks are used internally to inject functionality like authentication. For example, the internal authentication plugin is registering a request hook in lib/plugins/authentication/index.js. The method sets the authorization header based on authentication previously set using github.authenticate() before the ⑧ request.
Hooks will be used in future for request pagination, throttling and handling of rate limits.
Hooks can be registered using github.hook.{before|after}:
github.hook.before('request', (options) => {})
github.hook.after('request', (response, options) => {})The callbacks can return a Promise for asynchronous execution. options can be changed in the github.hook.before callback before they are transformed ⑥ transformed. The ⑩ response can be changed in the github.hook.after callback before it is returned to the user.