API版本控制的最佳做法？

Question

Web服务REST API版本是否存在任何已知的操作方法或最佳做法？

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

Answer 1

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

由于应用程序的发展以及在较小程度上其API的存在是不争的事实，并且它甚至与看似复杂的产品（如编程语言）的发展相似，因此URI设计应具有较少的自然约束，并且应予以保留随着时间的流逝。应用程序和API的寿命越长，对应用程序和API用户的承诺就越大。

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

随着时间的流逝，您可能需要向每个特定资源添加新资源和新属性，但是一旦资源寻址方案公开并最终确定，API用户访问特定资源所遵循的方法就不应更改。

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

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

当然，可以将API版本嵌入基本URI中，但仅用于合理和受限的用途，例如调试与新API版本一起使用的API客户端。这种版本化的API应该是有时间限制的，并且仅对有限的API用户组可用（例如在封闭Beta中）。否则，您将自己放在不应该的地方。

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

从API用户POV来看，只要很明显但仅在有限的时间内（即在开发过程中），就可以更轻松地使用和绑定到特定的API版本。

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

但是，在URI中清晰可见的API版本中，有一个警告：由于URI设计中的API历史变得可见/可见 ，因此可能会随着时间的推移而发生变化，这与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版本。因此，访问像这样的任何过时的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状态代码中的任何一个，这些状态代码与LocationHTTP标头结合使用，HTTP标头重定向到资源URI的适当版本，该版本仍为：

http：// shonzilla / api / customers / 1234

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

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

302找到，指示请求的资源临时位于另一个位置，而请求的URI可能仍受支持。当无版本URI暂时不可用，并且应该使用重定向地址（例如，指向嵌入了APi版本的URI）重复请求并且我们要告诉客户端继续使用它时，此状态代码可能很有用。永久链接）。