REST 版本控制 - URL 与标头

Question

我正计划编写一个 RESTful API，但我不知道如何处理版本控制。 我已经阅读了许多讨论和博客文章，其中建议使用接受标头进行版本控制。

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

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

Answer 1

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

优点和缺点（我敢肯定还有更多，其中一些缺点有此处未提及的变通办法）

1. 它更具探索性。对于大多数请求，您可以只使用浏览器，而 Resource Header 实现需要更程序化的测试方法。但是，由于并非所有 HTTP 请求都是可探索的，例如 POST 请求，您应该使用像 Postman 或 Paw 这样的 Rest Client 插件。 URI Pro/Header Con

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

3. URI 版本化的 API 更不容易出错，并且客户端开发人员更熟悉。通过 URL 进行版本控制允许开发人员一目了然地确定服务的版本。如果客户端开发人员忘记在标头中包含资源版本，您必须决定是否应将它们定向到最新版本（增加版本时可能会导致错误）或 301（永久移动）错误。无论哪种方式，对于您的新手客户端开发人员来说都会有更多的困惑。 URI Pro/Header Con
4. URI 版本控制有助于在同一应用程序中托管多个版本。在这种情况下，您不必进一步开发您的框架。 注意：如果这样做，您的目录结构很可能会在 v2 目录中包含大量重复代码。此外，部署更新需要重新启动系统 - 因此应尽可能避免使用此技术。 URI Pro/Header Con。
5. 对于从一开始就没有考虑版本控制的现有项目，将版本控制添加到 HTTP 标头会更容易。 Header Pro/URI Con。
6. 根据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