8

在某些示例中，我注意到了对 api 进行版本控制的两种方法。

其中之一是在 url 中使用一个版本

/api/v1/products

另一种是使用内容类型头和接受头来标记发送到服务器的数据的api版本

Content-Type=application/vnd.company.v2+xml

这种方法的优缺点是什么？您将使用每种方法的一些用例是什么？

4

3 回答 3

8

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

以下是我能找到的优点和缺点（我敢肯定还有更多，其中一些缺点有此处未提及的变通方法）

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

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

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

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

于 2015-06-17T01:11:39.710 回答
1

我已经习惯在 URL 本身 (/v1/) 中包含版本号。我个人认为这是一种更简洁的方法 - 这样，最终用户（或开发人员）不需要处理 HTTP 标头，并且可以简单地修改 REST API/调用以根据需要访问不同版本的 API。

我在想，也有可能一些不同语言的 HTTP API 可能不完全支持 HTTP 标头，因此您总是使 API 最容易为最终用户提供。重写 URL 是最简单的方法，它应该适用于任何支持 HTTP 的东西。

最后，允许使用 URL 指定 API 版本允许使用 Web 浏览器进行简单测试。如果将版本控制合并到 HTTP 标头中，开发人员将被迫使用编程语言进行测试。

于 2013-11-07T16:35:48.377 回答
0

最好在 URL 中使用版本。前段时间我一直在寻找这个，并偶然发现了以下 2 个资源，它们详细讨论了RESTful API 设计。

  1. 设计实用 RESTful API 的最佳实践-通过 URL 而不是通过标头的版本。
  2. programmers.stackexchange.com：对于 REST 端点规划有远见的更改，推荐的模式是什么？

TL;DR 答案：在 URL 中使用版本号是推荐的方法。

我遇到过的一些设计最完善的 API—— Instagram API和Stackoverflow.com API——都使用这种方法来控制 API 版本。

于 2013-11-07T22:45:02.897 回答