使用 REST API 的最佳做法

避免轮询

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

发出经身份验证的请求

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

避免并发请求

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

在可变请求之间暂停

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

恰当处理速率限制错误

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

• 如果出现 retry-after 响应头，则应首先等待所规定的数秒，然后再尝试请求。
• 如果 x-ratelimit-remaining 标头为 0，应在 x-ratelimit-reset 标头指定的时间之后再尝试发出另一个请求。 标头 x-ratelimit-reset 以 UTC 纪元秒为单位。
• 否则，请在重试之前等待至少一分钟。 如果请求由于次要速率限制而继续失败，请等待呈指数级增加的重试间隔秒数，当达到特定的重试次数之后，将会抛出错误。

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

遵循重定向

GitHub Enterprise Server 在适当情况下使用 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 标头。 可以使用这些标头的值发出条件请求。 如果响应未更改，将收到 304 Not Modified 响应。 如果系统返回 304 响应，则发出条件请求不会计入主要速率限制。

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

curl http(s)://HOSTNAME/api/v3/meta --include --header 'if-none-match: "644b5b0155e6404a9cc4bd9d8b1ae730"'

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

curl http(s)://HOSTNAME/api/v3/repos/github/docs --include --header 'if-modified-since: Wed, 25 Oct 2023 19:17:59 GMT'

请勿忽略错误

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

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

延伸阅读

• "使用 Webhook 的最佳做法"
• “创建 GitHub 应用的最佳做法”