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

Question

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

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

/api/v1/products

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

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

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

Answer 1

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

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

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

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

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

Answer 2

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

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

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

Answer 3

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

1. 设计实用的RESTful API的最佳做法 - Version via the URL, not via headers.
2. programmers.stackexchange.com ：What is a recommended pattern for REST endpoints planning for foresighted changes?

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

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