REST版本控制 - URL与标头

Question

我打算编写一个RESTful API，我对如何处理版本控制毫无头绪。 我已阅读了许多讨论和博客文章，建议使用accept标头进行版本控制。

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

为什么大多数人会说：“不要使用网址，而是使用接受标头”，但使用网址的流行API？

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 。

以下是一些有用的链接，如果您想进一步阅读：

• Martin Fowler's description of the Richardson Maturity Model
• API Versioning - Pivotal Labs
• HATEAOS
• Informit.com's Article on Versioning REST Services