Skip to main content

使用 REST API 的最佳做法

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

避免轮询

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

遵循 API 发送给您的任何重定向

GitHub 在资源发生移动时会通过提供重定向状态代码来明确告诉您。 您应该遵循这些重定向。 每个重定向响应都使用要转到的新 URI 来设置 Location 标头。 如果您收到了重定向,最好更新代码以遵循新的 URI,以防您请求我们可能已删除的无效路径。

我们提供了 HTTP 状态代码列表,你在设计应用以遵循重定向时需要注意这些代码。

不要手动解析 URL

通常,API 响应包含 URL 形式的数据。 例如,当请求存储库时,我们会发送一个名为 clone_url 的键,其中包含可用来克隆存储库的 URL。

为了应用程序的稳定性,您不应该尝试解析此数据,或者尝试猜测并构造未来 URL 的格式。 否则,如果我们决定更改该 URL,您的应用程序可能会中断。

例如,在处理分页结果时,人们往往很想构造在末尾追加 ?page=<number> 的 URL。 要抑制这种冲动。 有关可靠跟踪分页结果的详细信息,请参阅“在 REST API 中使用分页”。

处理 API 错误

尽管您的代码从未引入漏洞,但您可能会发现在尝试访问 API 时遇到连续错误。

你应该确保与 API 正确交互,而不是忽略重复的 4xx5xx 状态代码。 例如,如果某个终结点请求一个字符串,而你向其传递一个数值,则你将会收到 5xx 验证错误,并且你的调用不会成功。 同样,试图访问未经授权或不存在的终结点会导致 4xx 错误。

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

延伸阅读