【发布时间】:2011-01-02 17:37:48
【问题描述】:
我看过Best practices for API versioning?,但不太相信答案,所以我再次用一个更具体的例子来质疑版本控制部分。我有两个 URI(一个带有版本控制作为 URI 的一部分,一个没有):
http://xxxx/v1/user/123 -> favored solution in discussed thread
http://xxxx/user/123
我怀疑第一个链接是否表达了 REST 的想法。我发现 http://xxxx/v1/user/123 令人困惑,因为它暗示有一天会有更高的 api 版本,例如 http://xxxx/v2/user/123。但这在 REST 术语中没有意义,api 版本本身是 HTTP 1.0 或 1.1,它已经在 HTTP 请求内部发送。这种以 REST 资源为中心的视图与 SOAP 或 Java 接口等其他 api 接口非常不同(在这些接口中,api 版本的限定名称很常见)。
在 REST 中,唯一有意义的版本控制是该资源的表示(例如,添加或删除新字段)。此版本控制属于内容协商的一部分,例如:
http://xxx/user/123 + HTTP 'Accept' Header -> Content negotation through header
http://xxx/user/123?v=1 -> for perma-links/hyperlinks
也有人可能会争辩说,这种版本的内容协商可能是路径内 URI 的一部分,但我发现它违反直觉,因为您最终可能会为同一资源使用不同的 URI,并且必须在一点。
总结一下:在 REST URI 中没有 api 版本控制,只有资源表示的版本控制。表示版本信息属于内容协商(如 queryParam 或 HTTP 'Accept')。
你怎么看?您会在哪些方面不同意/同意?
【问题讨论】:
-
只需添加一点小东西。对我来说唯一使用 ...v1/ 样式的方法是,当您没有控制负载平衡并且无法在前端机器上基于 HTTP 标头定义到应用程序服务器的方向时(->内容协商是 HTTP 标头的一部分)。通常标准是使用 URL 路径。在网络框架中,我认为很难在控制器内部基于 HTTP 标头而不是路径来定义请求映射端点。
标签: rest versioning api-design