使用 REST API 的最佳做法

使用 GitHub 的 API 时，请遵循以下最佳做法。

本文内容

避免轮询

应订阅 Webhook 事件，而不是通过轮询 API 来获取数据。 这有助于将集成保持在 API 速率限制内。 有关详细信息，请参阅“Webhooks 文档”。

发出经身份验证的请求

经身份验证的请求的主要速率限制高于未经身份验证的请求。 为避免超出速率限制，应发出经过身份验证的请求。 有关详细信息，请参阅“REST API 的速率限制”。

避免并发请求

为避免超出辅助速率限制，应采用串行方式发出请求，而不是并行发出请求。 为此，可以为请求实施队列系统。

在可变请求之间暂停

如果要发出大量的 POST、PATCH、PUT 或 DELETE 请求，则请求之间至少应间隔一秒钟。 这将帮助您避免次级速率限制。

恰当处理速率限制错误

如果收到速率限制错误，应当根据以下指导原则暂时停止发出请求：

  • 如果有 retry-after 响应头，则应先等待数秒，然后再尝试请求。
  • 如果 x-ratelimit-remaining 标头为 0，应在 x-ratelimit-reset 标头指定的时间之后再尝试发出另一个请求。 标头 x-ratelimit-reset 以 UTC 纪元秒为单位。
  • 否则，请在重试之前等待至少一分钟。 如果您的请求因二级速率限制而持续失败，请在每次重试之间等待呈指数级增长的时间，并在达到特定重试次数后抛出一个错误。

如果在受到速率限制的情况下继续发出请求，可能会导致禁止集成。

了解 API 使用情况来洞察组织的发展趋势。

跟随重定向

GitHub REST API 在适当情况下使用 HTTP 重定向。 应假定任何请求都可能会导致重定向。 收到 HTTP 重定向不代表出现错误，应遵循该重定向。

          `301` 状态代码指示永久重定向。 应将请求重复到 `location` 标头指定的 URL。 此外，应更新代码以将此 URL 用于之后的请求。

          `302` 或 `307` 状态代码指示临时重定向。 应将请求重复到 `location` 标头指定的 URL。 但是，不应更新代码以将此 URL 用于之后的请求。

可能会根据 HTTP 规范使用其他重定向状态代码。

请勿手动分析 URL

许多 API 终结点会在响应正文中返回字段的 URL 值。 不应尝试分析这些 URL 或预测之后 URL 的结构。 如果将来 GitHub 更改 URL 结构，这可能会导致集成中断。 相反，应查找包含所需信息的字段。 例如，创建问题的终结点会返回一个 html_url 字段，其值类似 https://github.com/octocat/Hello-World/issues/1347，以及 number 字段，其值类似 1347。 如果需要知道问题的数量，请使用 number 字段，而不是分析 html_url 字段。

同样，不应尝试手动构造分页查询。 而是应使用链接标头来确定可以请求的结果页。 有关详细信息，请参阅“在 REST API 中使用分页”。

使用条件请求（如适用）

大多数终结点会返回 etag 标头，许多终结点会返回 last-modified 标头。 可以使用这些标头的值发出条件 GET 请求。 如果响应未更改，将收到 304 Not Modified 响应。 在正确使用 Authorization 标头授权的情况下发出条件请求时，如果返回 304 响应，则该请求不计入主速率限制。

例如，如果上一个请求返回 etag 标头，值为 644b5b0155e6404a9cc4bd9d8b1ae730，则可以在之后的请求中使用 if-none-match 标头：

curl -H "Authorization: Bearer YOUR-TOKEN" https://api.github.com/meta --include --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"'

例如，如果上一个请求返回 last-modified 标头，值为 Wed, 25 Oct 2023 19:17:59 GMT，则可以在之后的请求中使用 if-modified-since 标头：

curl -H "Authorization: Bearer YOUR-TOKEN" https://api.github.com/repos/github/docs --include --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT'

除非特定终结点的文档另有说明，否则不支持对不安全方法（例如 POST、PUT、PATCH 和 DELETE）的条件请求。

请勿忽略错误

不应忽略重复的 4xx 和 5xx 错误代码。 相反，应确保与 API 正确进行交互。 例如，如果某个终结点请求字符串，而你向其传递一个数值，则你将会收到验证错误。 同样，试图访问未经授权或不存在的终结点会导致 4xx 错误。

故意忽略重复的验证错误可能会导致您的应用程序因滥用而被暂停。

其他阅读材料

  •         [AUTOTITLE](/webhooks/using-webhooks/best-practices-for-using-webhooks)

  •         [AUTOTITLE](/apps/creating-github-apps/about-creating-github-apps/best-practices-for-creating-a-github-app)