REST 版本控制 - URL 与 header

Question

我打算编写一个 RESTful API，但我对如何处理版本控制一无所知。
我已经阅读了许多讨论和博客文章，其中建议使用 accept header 进行版本控制。

但后来我发现以下网站正在监听流行的 REST API 及其版本控制方法，其中大多数使用 URL 进行版本控制。
为什么？

为什么大多数人说:“不要使用 URL，而是使用接受 header ”，而流行的 API 使用 URL？

Answer 1

这两种机制都是有效的。您需要了解您的消费者才能知道该走哪条路。一般来说，与企业和有学术头脑的人合作往往会将开发人员指向资源头版本控制。但是，如果您的客户是较小的企业，则 URL 版本控制方法会得到更广泛的使用。

优点和缺点(我相信还有更多，其中一些缺点有此处未提及的变通方法)

它更具探索性。对于大多数请求，您可以只使用浏览器，而 Resource Header 实现需要更程序化的测试方法。然而，因为不是所有的 HTTP 请求都是可探索的，例如 POST 请求，你应该使用一个 Rest Client 插件，比如 Postman或 Paw . URI Pro/Header Con

使用 URI 版本化 API，资源标识和资源的表示被混合在一起。这违反了 REST 的基本原则；一种资源应由一个且仅一个端点标识。在这方面，Resource Header 版本控制选择在学术上更加理想化。 标题 Pro/URI Con .

URI 版本化 API 不易出错，客户端开发人员更熟悉。通过 URL 进行版本控制允许开发人员一目了然地确定服务的版本。如果客户端开发人员忘记在 header 中包含资源版本，您必须决定是将它们定向到最新版本(增加版本时可能会导致错误)还是 301(永久移动)错误。无论哪种方式，您的新手客户端开发人员都会更加困惑。 URI Pro/Header Con

URI 版本控制有助于在同一应用程序中托管多个版本。在这种情况下，您不必进一步开发您的框架。
注意:如果您这样做，您的目录结构很可能会在 v2 目录中包含大量重复代码。此外，部署更新需要重新启动系统 - 因此应尽可能避免使用此技术。 URI Pro/Header Con .

对于从一开始就没有考虑版本控制的现有项目，将版本控制添加到 HTTP header 会更容易。 标题 Pro/URI Con .

根据RMM Level 3 REST Principle: Hypermedia Controls ，您应该使用 HTTP Accept 和 Content-Type header 来处理数据的版本控制以及描述数据。 标题 Pro/URI Con .

如果您想进一步阅读，这里有一些有用的链接:

Martin Fowler's description of the Richardson Maturity Model

API Versioning - Pivotal Labs

HATEAOS

Informit.com's Article on Versioning REST Services