1. 首页
  2. 问题
  3. API 版本控制的最佳实践？
小编典典

API 版本控制的最佳实践？

all

是否有任何已知的 Web 服务 REST API 版本控制方法或最佳实践？

我注意到AWS 通过端点的 URL
进行版本控制。这是唯一的方法还是有其他方法可以实现相同的目标？如果有多种方式，每种方式的优点是什么？


阅读 106

收藏
2022-03-01

共1个答案

小编典典

这是一个很好但很棘手的问题。 URI 设计 主题同时 是 REST API 中最突出的部分 ，因此是对该 API 用户的潜在
长期承诺 。

由于应用程序及其 API 的演变是不争的事实，甚至类似于编程语言等看似复杂的产品的演变，因此 URI 设计 应具有较少 的自然约束 并
应保留随着时间的推移 。应用程序和 API 的生命周期越长，对应用程序和 API 用户的承诺就越大。

另一方面，生活中的另一个事实是，很难预见将通过 API 消耗的所有资源及其方面。幸运的是，没有必要设计整个
API，直到Apocalypse才会使用。正确定义所有资源端点以及每个资源和资源实例的寻址方案就足够了。

随着时间的推移，您可能需要为每个特定资源添加新资源和新属性，但是一旦资源寻址方案公开并因此成为最终方案，API 用户访问特定资源所遵循的方法不应改变。

此方法适用于早期 API 版本中支持的 HTTP 动词语义（例如 PUT 应始终更新/替换）和 HTTP
状态代码（它们应继续工作，以便在没有人工干预的情况下工作的 API 客户端应该能够继续工作像那样）。

此外，由于将 API 版本嵌入 URI
会破坏超媒体作为应用程序状态引擎的概念（在
Roy T. Fieldings 博士论文中陈述），因为资源地址/URI 会随时间变化，我会得出结论， API版本不应长时间保存在资源 URI 中，
这意味着 API 用户可以依赖的资源 URI 应该是永久链接 。

当然， 可以在基本 URI 中嵌入 API 版本， 但 仅限于合理且受限的用途，例如调试 与新 API 版本一起使用的 API
客户端。此类版本化的 API 应该是有时间限制的，并且仅对有限的 API 用户组可用（例如在封闭测试期间）。否则，你会在不应该的地方做出承诺。

关于维护有过期日期的 API 版本的一些想法。所有通常用于实现 Web 服务的编程平台/语言（Java、.NET、PHP、Perl、Rails 等）都允许将
Web 服务端点轻松绑定到基本 URI。通过这种方式，很容易 收集并保持 文件/类/方法的集合 在不同的 API 版本中分开 。

从 API 用户 POV 来看，当它很明显但仅限于有限的时间时，即在开发期间，使用和绑定到特定的 API 版本也更容易。

从 API 维护者的 POV 来看，通过使用主要处理文件作为（源代码）版本控制的最小单元的源代码控制系统，可以更轻松地并行维护不同的 API 版本。

但是，由于 API 版本在 URI 中清晰可见，有一个警告：人们也可能反对这种方法，因为 API 历史在 URI 设计中变得可见/透明
，因此随着时间的推移容易发生变化， 这违反了 REST 的准则。我同意！

绕过这个合理反对的方法是在无版本 API 基础 URI 下实现最新的 API 版本。在这种情况下，API 客户端开发人员可以选择：

  • 针对最新的开发（承诺自己维护应用程序，保护它免受可能破坏他们 设计糟糕的 API 客户端 的最终 API 更改）。

  • 绑定到特定版本的 API（这很明显），但仅限于有限的时间

例如，如果 API v3.0 是最新的 API 版本，则以下两个应该是别名（即对所有 API 请求的行为相同）：

**http://shonzilla/api/customers/1234** 
http://shonzilla/api **/v3.0** /customers/1234
http://shonzilla/api **/v3** /customers/1234

此外，如果 API 客户端正在使用的API 版本已过时或不再受支持，* 则应通知仍尝试指向 旧 API 的 API 客户端使用最新的先前 API
版本。因此，访问任何过时的 URI，如下所示： *

 http://shonzilla/api **/v2.2** /customers/1234
http://shonzilla/api **/v2.0** /customers/1234
http://shonzilla/api **/v2** /customers/1234
http://shonzilla/api **/v1.1** /customers/1234
http://shonzilla/api **/v1** /customers/1234

应该返回 指示重定向的任何 30x HTTP 状态代码，这些代码 与 HTTP 标头一起使用，Location该标头重定向到资源 URI
的适当版本，该版本仍然是这个：

**http://shonzilla/api/customers/1234**

至少有两个重定向 HTTP 状态代码适用于 API 版本控制方案：

  • 301 Moved Permanent表示具有请求 URI 的资源被永久移动到另一个 URI（应该是不包含 API 版本信息的资源实例永久链接）。此状态码可用于指示过时/不受支持的 API 版本，通知 API 客户端 版本化资源 URI 已被资源永久链接替换 。

  • 302 Found表示请求的资源暂时位于另一个位置，而请求的URI可能仍然支持。当无版本 URI 暂时不可用并且应该使用重定向地址重复请求（例如，指向嵌入了 APi 版本的 URI）并且我们想告诉客户端继续使用它（即永久链接）。

  • 其他场景参见HTTP 1.1 规范的 Redirection 3xx 章节

2022-03-01