From df0670cb8fc748565df984e4774af6ccc807f274 Mon Sep 17 00:00:00 2001 From: Gregor Martynus Date: Thu, 10 Sep 2020 15:39:50 -0700 Subject: [PATCH] refactor: update URLs (#1863) * style: prettier * refactor: update URLs to new website: https://docs.github.com/rest/ * build(package): apply prettier to all `*.md` files in root folder --- CODE_OF_CONDUCT.md | 20 ++++++------- HOW_IT_WORKS.md | 30 +++++++++++-------- README.md | 2 +- docs/src/pages/api/00_usage.md | 8 ++--- docs/src/pages/api/01_authentication.md | 2 +- docs/src/pages/api/02_previews.md | 2 +- docs/src/pages/api/03_request_formats.md | 4 +-- docs/src/pages/api/05_pagination.md | 4 +-- docs/src/pages/api/09_throttling.md | 2 +- package.json | 4 +-- test/integration/deprecations-test.js | 6 ++-- ...-error-message-on-validation-error-test.js | 2 +- 12 files changed, 45 insertions(+), 41 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 8124607b..cd02cdb9 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -8,19 +8,19 @@ In the interest of fostering an open and welcoming environment, we as contributo Examples of behavior that contributes to creating a positive environment include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members Examples of unacceptable behavior by participants include: -* The use of sexualized language or imagery and unwelcome sexual attention or advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a professional setting +- The use of sexualized language or imagery and unwelcome sexual attention or advances +- Trolling, insulting/derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information, such as a physical or electronic address, without explicit permission +- Other conduct which could reasonably be considered inappropriate in a professional setting ## Our Responsibilities diff --git a/HOW_IT_WORKS.md b/HOW_IT_WORKS.md index 529b8726..d99c66f4 100644 --- a/HOW_IT_WORKS.md +++ b/HOW_IT_WORKS.md @@ -12,9 +12,10 @@ 4. [Hooks ⑤ & ⑨](#request) + ## Endpoint options (① - ④) -`@octokit/rest` exposes a method for each [REST API endpoint](https://developer.github.com/v3/), for example `octokit.repos.listForOrg()` for [`GET /orgs/:org/repos`](https://developer.github.com/v3/repos/#list-organization-repositories). The methods are generated in [`@octokit/plugin-rest-endpoint-methods`](https://github.com/octokit/plugin-rest-endpoint-methods.js/). The [`src/generated/endpoints.ts` file](https://github.com/octokit/plugin-rest-endpoint-methods.js/blob/master/src/generated/endpoints.ts) defines the **② endpoint default options** `method`, `url`, and in some cases `mediaType` and `headers`. +`@octokit/rest` exposes a method for each [REST API endpoint](https://docs.github.com/en/rest/reference/), for example `octokit.repos.listForOrg()` for [`GET /orgs/:org/repos`](https://docs.github.com/en/rest/reference/repos/#list-organization-repositories). The methods are generated in [`@octokit/plugin-rest-endpoint-methods`](https://github.com/octokit/plugin-rest-endpoint-methods.js/). The [`src/generated/endpoints.ts` file](https://github.com/octokit/plugin-rest-endpoint-methods.js/blob/master/src/generated/endpoints.ts) defines the **② endpoint default options** `method`, `url`, and in some cases `mediaType` and `headers`. **② endpoint default options** are merged with **① global defaults**, which are based on [@octokit/endpoint/src/defaults.ts](https://github.com/octokit/endpoint.js/blob/master/src/defaults.ts) and the options that were passed into the `new Octokit(options)` constructor. @@ -23,7 +24,7 @@ Both are merged with **③ user options** passed into each method. Altogether th **Example**: get all public repositories of the the [@octokit](https://github.com/octokit) GitHub organization. ```js -octokit.repos.listForOrg({ org: 'octokit', type: 'public' }) +octokit.repos.listForOrg({ org: "octokit", type: "public" }); ``` **④ endpoint options** will be @@ -74,6 +75,7 @@ octokit.repos.listForOrg({ org: 'octokit', type: 'public' }) + ## Transform endpoint to request options (⑥ - ⑦) **④ Endpoint options** are **⑥ transformed** into **⑦ request options** using [@octokit/endpoint](https://github.com/octokit/endpoint.js). @@ -101,6 +103,7 @@ For example, the endpoint options shown above would result in + ## 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. @@ -108,6 +111,7 @@ Using **⑦ request options**, a **⑧ request** is sent to the GitHub REST API. Requests are sent using [`@octokit/request`](https://github.com/octokit/request.js). It's using the native fetch method in the browsers and [node-fetch](https://github.com/bitinn/node-fetch) in other environments. + ## Hooks ⑤ & ⑨ Hooks are used to inject functionality like authentication. For example, the [request log plugin](https://github.com/octokit/plugin-request-log.js) is registering a request hook in [src/index.ts](https://github.com/octokit/plugin-request-log.js/blob/e8308e36e049946a0b1813b8b25aa28d4a6c8789/src/index.ts#L9-L35). A debug message is logged before sending the request, and an info message is logged once a response is received. @@ -115,20 +119,20 @@ Hooks are used to inject functionality like authentication. For example, the [re Hooks can be registered using `octokit.hook.{before|after|error|wrap}`: ```js -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) => { +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) + return findInCache(error.headers.etag); } - throw error -}) -octokit.hook.wrap('request', async (request, options) => {}) + 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**. 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. diff --git a/README.md b/README.md index faaae748..02da84df 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ npm install @octokit/rest const { Octokit } = require("@octokit/rest"); const octokit = new Octokit(); -// Compare: https://developer.github.com/v3/repos/#list-organization-repositories +// Compare: https://docs.github.com/en/rest/reference/repos/#list-organization-repositories octokit.repos .listForOrg({ org: "octokit", diff --git a/docs/src/pages/api/00_usage.md b/docs/src/pages/api/00_usage.md index df87e3e4..fb26de66 100644 --- a/docs/src/pages/api/00_usage.md +++ b/docs/src/pages/api/00_usage.md @@ -49,7 +49,7 @@ Learn more about [authentication](#authentication). auth: "secret123", ``` -Setting a user agent [is required](https://developer.github.com/v3/#user-agent-required). It defaults to `octokit/rest.js v1.2.3` where `v1.2.3` is the current version of `@octokit/rest`, but you should set it to something that identifies your app or script. +Setting a user agent [is required](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#user-agent-required). It defaults to `octokit/rest.js v1.2.3` where `v1.2.3` is the current version of `@octokit/rest`, but you should set it to something that identifies your app or script. ```js userAgent: 'myApp v1.2.3', @@ -69,7 +69,7 @@ A default time zone can be enabled by setting the `timeZone` option. timeZone: 'Europe/Amsterdam', ``` -Learn more about [using time zones with the GitHub API](https://developer.github.com/v3/#using-the-time-zone-header). +Learn more about [using time zones with the GitHub API](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#timezones). In order to use Octokit with GitHub Enterprise, set the `baseUrl` option. @@ -117,7 +117,7 @@ const { data: pullRequest } = await octokit.pulls.get({ }); ``` -Some API endpoints support alternative response formats, see [Media types](https://developer.github.com/v3/media/). For example, to [request the above pull request in a diff format](https://developer.github.com/v3/media/#diff), pass the `mediaType.format` option. +Some API endpoints support alternative response formats, see [Media types](https://docs.github.com/en/rest/overview/media-types). For example, to [request the above pull request in a diff format]((https://docs.github.com/en/rest/overview/media-types/#diff), pass the `mediaType.format` option. Learn more about [request formats](#request-formats). @@ -132,7 +132,7 @@ const { data: diff } = await octokit.pulls.get({ }); ``` -For the API endpoints that do not have a matching method, such as the [root endpoint](https://developer.github.com/v3/#root-endpoint) or legacy endpoints, you can send custom requests. +For the API endpoints that do not have a matching method, such as the [root endpoint](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#root-endpoint) or legacy endpoints, you can send custom requests. Learn more about [custom requests](#custom-requests). diff --git a/docs/src/pages/api/01_authentication.md b/docs/src/pages/api/01_authentication.md index 966bc54c..02677595 100644 --- a/docs/src/pages/api/01_authentication.md +++ b/docs/src/pages/api/01_authentication.md @@ -2,7 +2,7 @@ title: "Authentication" --- -Authentication is optional for some REST API endpoints accessing public data, but is required for GraphQL queries. Using authentication also increases your [API rate limit](https://developer.github.com/v3/#rate-limiting). +Authentication is optional for some REST API endpoints accessing public data, but is required for GraphQL queries. Using authentication also increases your [API rate limit](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting). By default, Octokit authenticates using the [token authentication strategy](https://github.com/octokit/auth-token.js). Pass in a token using `options.auth`. It can be a personal access token, an OAuth token, an installation access token or a JSON Web Token for GitHub App authentication. The `Authorization` header will be set according to the type of token. diff --git a/docs/src/pages/api/02_previews.md b/docs/src/pages/api/02_previews.md index c943d346..2a5768d7 100644 --- a/docs/src/pages/api/02_previews.md +++ b/docs/src/pages/api/02_previews.md @@ -2,7 +2,7 @@ title: "Previews" --- -To enable any of [GitHub’s API Previews](https://developer.github.com/v3/previews/), +To enable any of [GitHub’s API Previews](https://docs.github.com/en/rest/overview/api-previews/), pass the `previews` option to the GitHub constructor ```js diff --git a/docs/src/pages/api/03_request_formats.md b/docs/src/pages/api/03_request_formats.md index 9ea63f6d..8dd90a71 100644 --- a/docs/src/pages/api/03_request_formats.md +++ b/docs/src/pages/api/03_request_formats.md @@ -2,9 +2,9 @@ title: "Request formats & aborts" --- -Some API endpoints support alternative response formats, see [Media types](https://developer.github.com/v3/media/). +Some API endpoints support alternative response formats, see [Media types](https://docs.github.com/en/rest/reference/media/). -For example, to request a [pull request as diff format](https://developer.github.com/v3/media/#diff), set the `mediaType.format` option +For example, to request a [pull request as diff format](https://docs.github.com/en/rest/reference/media/#diff), set the `mediaType.format` option ```js const { data: prDiff } = await octokit.pulls.get({ diff --git a/docs/src/pages/api/05_pagination.md b/docs/src/pages/api/05_pagination.md index a0d29aa6..f36b0300 100644 --- a/docs/src/pages/api/05_pagination.md +++ b/docs/src/pages/api/05_pagination.md @@ -2,7 +2,7 @@ title: "Pagination" --- -All endpoint methods starting with `.list*` do not return all results at once but instead return the first 30 items by default, see also [GitHub’s REST API pagination documentation](https://developer.github.com/v3/#pagination). +All endpoint methods starting with `.list*` do not return all results at once but instead return the first 30 items by default, see also [GitHub’s REST API pagination documentation](https://docs.github.com/en/rest/overview/resources-in-the-rest-api#pagination). To automatically receive all results across all pages, you can use the `octokit.paginate()` method: @@ -20,7 +20,7 @@ octokit `octokit.paginate()` accepts the same options as [`octokit.request()`](#custom-requests). You can optionally pass an additional function to map the results from each response. The map must return a new value, usually an array with mapped data. -**Note:** the map function is called with the `{ data, headers, status, url }` response object. The `data` property is guaranteed to be an array of the result items, even for list endpoints that respond with an object instead of an array, such as the [search endpoints](https://developer.github.com/v3/search/#example). +**Note:** the map function is called with the `{ data, headers, status, url }` response object. The `data` property is guaranteed to be an array of the result items, even for list endpoints that respond with an object instead of an array, such as the [search endpoints](https://docs.github.com/en/rest/reference/search/#example). ```js octokit diff --git a/docs/src/pages/api/09_throttling.md b/docs/src/pages/api/09_throttling.md index 21c27e8a..562483ea 100644 --- a/docs/src/pages/api/09_throttling.md +++ b/docs/src/pages/api/09_throttling.md @@ -4,7 +4,7 @@ title: "Throttling" When you send too many requests in too little time you will likely hit errors due to rate and/or abuse limits. -In order to automatically throttle requests as recommended in [GitHub’s best practices for integrators](https://developer.github.com/v3/guides/best-practices-for-integrators/), we recommend you install the [`@octokit/plugin-throttling` plugin](https://github.com/octokit/plugin-throttling.js). +In order to automatically throttle requests as recommended in [GitHub’s best practices for integrators](https://docs.github.com/en/rest/reference/guides/best-practices-for-integrators/), we recommend you install the [`@octokit/plugin-throttling` plugin](https://github.com/octokit/plugin-throttling.js). The `throttle.onAbuseLimit` and `throttle.onRateLimit` options are required. diff --git a/package.json b/package.json index 60b274b6..30425aa8 100644 --- a/package.json +++ b/package.json @@ -58,8 +58,8 @@ "scripts": { "build": "pika build", "coverage": "nyc report --reporter=html && open coverage/index.html", - "lint": "prettier --check '{src,test}/**/*.{js,json,ts}' 'docs/*.{js,json}' 'docs/src/**/*' README.md package.json", - "lint:fix": "prettier --write '{src,test}/**/*.{js,json,ts}' 'docs/*.{js,json}' 'docs/src/**/*' README.md package.json", + "lint": "prettier --check '{src,test}/**/*.{js,json,ts}' 'docs/*.{js,json}' 'docs/src/**/*' *.md package.json", + "lint:fix": "prettier --write '{src,test}/**/*.{js,json,ts}' 'docs/*.{js,json}' 'docs/src/**/*' *.md package.json", "start-fixtures-server": "octokit-fixtures-server", "pretest": "npm run -s lint", "test": "jest --coverage", diff --git a/test/integration/deprecations-test.js b/test/integration/deprecations-test.js index 21fc0179..6d9c22ef 100644 --- a/test/integration/deprecations-test.js +++ b/test/integration/deprecations-test.js @@ -1075,9 +1075,9 @@ describe("deprecations", () => { * URL though: `/applications/:client_id/tokens/:access_token`. We identify this acception by looking * for this path. * - * 1. [Check an authorization](https://developer.github.com/v3/oauth_authorizations/#check-an-authorization) - * 2. [Reset an authorization](https://developer.github.com/v3/oauth_authorizations/#reset-an-authorization) - * 3. [Revoke an authorization for an application](https://developer.github.com/v3/oauth_authorizations/#revoke-an-authorization-for-an-application) + * 1. [Check an authorization](https://docs.github.com/en/rest/reference/apps/#check-an-authorization) + * 2. [Reset an authorization](https://docs.github.com/en/rest/reference/apps/#reset-an-authorization) + * 3. [Revoke an authorization for an application](https://docs.github.com/en/rest/reference/apps/#revoke-an-authorization-for-an-application) */ it("OAuth client & secret to check authorization", () => { nock("https://authentication-test-host.com", { diff --git a/test/issues/1497-include-error-message-on-validation-error-test.js b/test/issues/1497-include-error-message-on-validation-error-test.js index 330a37e3..acacef1f 100644 --- a/test/issues/1497-include-error-message-on-validation-error-test.js +++ b/test/issues/1497-include-error-message-on-validation-error-test.js @@ -29,7 +29,7 @@ describe("https://github.com/octokit/rest.js/issues/1497", () => { "Only organization repositories can have users and team restrictions", ], documentation_url: - "https://developer.github.com/v3/repos/branches/#update-branch-protection", + "https://docs.github.com/en/rest/reference/repos/#update-branch-protection", }); const octokit = new Octokit({