api版本控制方法的优缺点是什么？

Question

我在一些例子中注意到两种版本化api的方法。

其中一个是在网址中使用版本

/api/v1/products

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

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

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

Answer 1

两种机制都是有效的。 您需要了解您的消费者以了解要遵循的路径。 一般而言，与企业和有学术头脑的人合作往往会将开发人员指向资源标题版本。 但是，如果您的客户是较小的企业，则URL版本控制方法会得到更广泛的使用。

以下是我能找到的优点和缺点（我确信还有更多，而且有些Cons还没有提到这里的工作）

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

2. 使用URI版本的API，资源标识和资源的表示被一起使用。 这违反了REST的基本原则; 一个资源应由一个且仅一个端点标识。 在这方面，资源标题版本选择在学术上更具理想性。 标题Pro / URI Con 。

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

如果您想进一步阅读，请参阅以下链接：

• Martin Fowler对Richardson成熟度模型的描述
• API版本控制 - Pivotal Labs
• HATEAOS
• Informit.com关于版本化REST服务的文章

Answer 2

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

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

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

Answer 3

最好在URL中使用版本。 我一直在寻找这个，并遇到了以下2个资源，详细讨论了RESTful API设计 。

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

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

我遇到过的一些设计最好的API-- Instagram API和Stackoverflow.com API - 都使用这种方法进行API版本控制。