API 版本管理与弃用政策

了解 Inblog 如何支持 API v1、宣布未来的弃用计划并安排支持结束。

Inblog 将 REST API 的版本写在 URL 路径中，让自动化程序可以使用可预测的契约。

当前支持

v1 是当前受支持的 REST API 版本。创建集成时，请使用 /api/v1/... 下的端点和 OpenAPI 文档。

对于受支持的操作，我们会在 v1 内保持向后兼容。新增响应字段等不破坏兼容性的改进可以在不创建新 URL 版本的情况下发布。目前尚未公布 v1 的弃用或停止支持日期。

API 目前不会仅仅因为存在本政策，就为 v1 发送 Deprecation 或 Sunset 响应标头。没有这些标头表示尚未公布退出支持的信号。

如果计划停止支持某个 API 版本，Inblog 可能会使用以下响应标头：

这两个信号含义不同：弃用标志着生命周期变化，而 Sunset 指明计划中的支持结束时间。出现这些标头时，客户端应记录两个标头，并查看链接的文档或迁移指南。

按照通常政策，在移除 v1 或对受支持的 API 版本进行不兼容更改之前，我们至少提前 180 天通知。这个期限是保守的最低标准，并不承诺每次更改都会严格按照该时间表进行。

安全漏洞、法律要求或紧急情况可能需要缩短通知期限或立即更改。在这些情况下，我们会尽可能早地说明影响和可用的修复措施。