API版本控制方法的利弊是什么

Question

我在某个示例中注意到了两种版本控制API的方法。

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

/api/v1/products

另一个是使用内容类型标头和Accept标头来标记数据发送到服务器的API版本

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

这种方法有什么利弊？您将使用每种方法的哪些用例？

Answer 1

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

我认为，以不同语言的某些HTTP API也可能没有完全支持HTTP标头，因此您始终使最终用户最容易获得API。重新编写URL是最简单的方法，它应该与支持HTTP的任何东西一起使用。

最后，允许使用URL指定API版本可以使用Web浏览器进行简单测试。如果将版本控制纳入HTTP标题，则开发人员将被迫使用编程语言进行测试。

Answer 2

两种机制都是有效的。您需要了解您的消费者才能知道要遵循的路径。总的来说，与企业和学术意识的人一起工作倾向于将开发人员指向资源标题版本。但是，如果您的客户是较小的企业，则更广泛地使用URL版本控制方法。

这是我能找到的利弊（我敢肯定还有更多，有些缺点在这里没有提及）

1. 它更具探索性。对于大多数请求，您只需使用浏览器，而资源标头实现需要更具程序性的测试方法。但是，由于并非所有HTTP请求都是可探索的，例如，发布请求，您应该使用REST客户端插件 邮差 或者 爪子. URI Pro/Header Con

2. 凭借尿液转化的API，资源标识和资源的表示形式被汇总在一起。这违反了休息的基本原则；一个资源应通过一个又一个端点来识别。在这方面，资源标题版本控制选择在学术上更为理想主义。 标题Pro/Uri Con.

3. 尿道反复的API较少易于易于，并且对客户开发人员更熟悉。由URL版本控制，开发人员可以一目了然地找出服务的版本。 f客户开发人员忘记在标题中包括资源版本，您必须确定它们是否应针对最新版本（在递增版本时可能会导致错误）或301（永久移动）错误。无论哪种方式，您的新手客户开发人员都会感到更加混乱。 URI Pro/Header Con
4. URI版本控制将自己用于在同一应用程序中使用多个版本。在这种情况下，您不必进一步开发框架。注意：如果执行此操作，您的目录结构很可能在V2目录中包含大量重复代码。此外，部署更新需要系统重新启动 - 因此，应避免使用此技术。 URI Pro/Header Con.
5. 为现有项目的HTTP标头添加版本控制更容易，该项目尚未在其启动开始时考虑版本。 标题Pro/Uri Con.
6. 根据 RMM级别3休息原理：超媒体控制, ，您应该使用HTTP Accept和Content-Type标头来处理数据的版本以及描述数据。 标题Pro/Uri Con.
7. 当您将版本放入URL中时，您的客户需要将其代码（或者如果它们智能，配置）进行协调为新的API。 标题Pro/Uri Con.

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

• 马丁·福勒（Martin Fowler）对理查森成熟模型的描述
• API版本 - 关键实验室
• Hateaos
• Informit.com关于版本控制REST服务的文章

Answer 3

最好在URL中使用版本。我一直在寻找这一点，并遇到了以下2个资源来讨论 宁静的API设计 最后。

1. 设计务实的RESTFUL API的最佳实践 - 通过URL，而不是通过标头进行版本。
2. programmers.stackexchange.com : 对于预见更改的REST端点计划的推荐模式是什么？

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

我遇到过的一些最井井有条的工作 - Instagram API 和 stackoverflow.com API - 两者都使用此方法进行API版本控制。