什么是适当的api uri版本格式？

Question

我从以前的开发人员继承了开发中的API，该开发人员使用以下API uri模式进行版本控制：

http://localhost:8080/api/v1/users/

这是API版本控制的正确格式吗？例如，如果客户端需要用户API的v2，那么以下uri格式似乎表示用户存在API的v2，但不一定表示所有实体都存在API的v2：

http://localhost:8080/api/users/v2

所以看起来第二个uri会更精细。这些模式中的一种是否比另一种更正确或更常用？

Answer 1

我使用前者：/api/v1/users/因为：

• 如果新版本的API作为Web应用程序的单独实例公开，那么配置站点范围的路由要容易得多：只需将/api/v1/...之后的所有请求路由到旧版本并{{1到新版本。如果/api/v2/...位于URI的末尾，那么配置路由将是一件痛苦的事。
• API的新版本可能会使更高级别过时，如果＆＃34;用户＆＃34;用＃34;身份＆＃34;代替？那么＆＃34; v2＆＃34;后缀变得毫无意义。
• 资源路径是层次结构 - 在应该使用资源来引用该资源的版本之后具有版本指示符，例如，如果您想获得v2状态的第二个快照，那么可能是User 123并获得第300个快照，然后/api/users/123/v2 - 将API版本信息放在那里这让人不清楚。
• 资源路径应该从左到右，从最少到最具体的＆＃34;订购。最终的API版本会破坏逻辑顺序。
• 同样，/api/users/123/v300表示＆＃34; API版本1下的用户＆＃34; - 而不是/api/v1/users，在这种情况下，它变得不清楚（＆＃34; API的版本1用户＆＃34;？＆＃34; API下的用户名为＆＃39; v1＆＃39;＆＃ 34;等）。

还有其他方法需要考虑：如果您的版本控制仅涉及DTO的不同架构版本，而基础数据和业务逻辑保持不变，那么您可以让客户端指定DTO架构版本他们想要一个查询字符串值：

/api/users/v1