REST api 版本控制(仅版本表示，而不是资源本身) [英] REST api versioning (only version the representation, not the resource itself)

问题描述

我查看了API 版本控制的最佳实践?，但我没有非常相信答案，所以我用一个更具体的例子再次质疑版本控制部分.我有两个 URI(一个带有版本控制作为 URI 的一部分，另一个没有):

I had a look at Best practices for API versioning?, but am not quite convinced of the answer, so I am question the versioning part again with a more specific example. I am having two URIs (one with versioning as part of the URI and one without):

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 版本).

I am having my doubts whether the first link expresses the idea of REST. I find http://xxxx/v1/user/123 confusing as it suggests that there will be a higher api-version someday like http://xxxx/v2/user/123. But this does not make sense in REST terms, the api version itself is HTTP 1.0 or 1.1, which is already sent inside the HTTP request. This REST resource centric view differs very from other api-interfaces like SOAP or Java-interfaces (where it is common to have api-versions in qualified names).

在 REST 中，版本控制唯一有意义的是该资源的表示(例如添加或删除新字段).此版本控制属于内容协商的一部分，例如:

At REST the only thing where versioning makes sense is the representation of that resource (e.g. new fields are added or removed). This versioning belongs to the part of content-negotiation like:

http://xxx/user/123 + HTTP 'Accept' Header -> Content negotation through header
http://xxx/user/123?v=1                    -> for perma-links/hyperlinks

也有人可能会争辩说，这样的版本内容协商可能是路径内 URI 的一部分，但我觉得这违反直觉，因为您可能最终会为同一资源使用不同的 URI，并且必须在以下位置维护重定向某个点.

One could also argue that such version content-negotiation could be part of the URI inside the path, but I find it counter-intuitive, because you could end-up with different URIs for the same resource and have to maintain redirects at some point.

总而言之:在 REST URI 中，没有 api 版本控制，只有资源表示的版本控制.表示版本信息属于内容协商(如 queryParam 或 HTTP 'Accept').

To sum-up: In REST URIs there is no api-versioning, only versioning of the resource's representation. Representation version-info belongs to content-negotiation (as queryParam or HTTP 'Accept').

你怎么看?您不同意/同意哪些方面?

What do you think? In which things would you disagree/agree?

推荐答案

我完全同意；URI 表示身份，新版本引入时身份不会改变.当然，可能会有其他概念的新 URI，并且现有的 URI 可能会重定向……但在 URI 中包含v2"对我来说是 RPCish.

I completely agree; a URI expresses identity, identity doesn't change when a new version is introduced. There might be new URIs for additional concepts, of course, and existing URIs might redirect … but including a "v2" in the URI smells RPCish to me.

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

Note that this has got nothing to do with REST, really, as from a REST perspective it's all just characters.

这篇关于REST api 版本控制(仅版本表示，而不是资源本身)的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！