REST api版本控制(仅表示表示,而不是资源本身)

Question

我看了一下API版本的最佳实践？,但我不太相信答案,所以我再次用更具体的例子质疑版本控制部分.我有两个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资源为中心的视图与其他api接口(如SOAP或Java接口)非常不同(其中通常有限定名称的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'接受').

你怎么看？你不同意/同意哪些事情？

Answer 1

我完全同意; URI表示标识,引入新版本时标识不会更改.当然,可能有新的URI用于其他概念,现有的URI可能会重定向......但是在URI中包含"v2"会让我感到厌恶.

请注意,这与REST无关,实际上,从REST角度来看,它只是字符.

Answer 2

您可以侦听X-API-VersionHTTP请求标头.如果标头存在,则服务器必须使用该版本的API.如果标头不存在,则服务器可以使用最新版本的API.

> GET /user/123 HTTP/1.1
> Host: xxx
> X-API-Version: >=1.5.1, <2.0.0
> Accept: application/json
>

< HTTP/1.1 200 OK
< X-API-Version: 1.6.12
<
< { "user": { "id": 123, "name": "Bob Smith" } }
<

Answer 3

对于它的价值,我同意你的观点Manuel.你可以在这个问题中看到我的推理如何版本REST URI

有很多人似乎不同意但我不担心.只要您尊重超文本约束,您的网址看起来确实对您的客户端没有太大影响.