使用 XML 和 JSON Content-Type 对 RESTful API 进行版本控制答案

【问题标题】：Versioning a RESTful API with both XML and JSON Content-Type使用 XML 和 JSON Content-Type 对 RESTful API 进行版本控制
【发布时间】：2012-08-15 18:32:15
【问题描述】：

根据this excellent presentation 设计 RESTful 接口，实现版本控制的首选方法是利用 Accept-header，使用类似的东西：

GET /products HTTP/1.1
Host: example.com
Accept: application/vnd.com.myservice.v2+xml

这对 XML 内容类型非常有效，但是是否可以使用相同的方案来控制 JSON 等效项？

即，是否可以要求：

GET /products HTTP/1.1
Host: example.com
Accept: application/vnd.com.myservice.v2+json

响应会是这样的：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.myservice.v2+xml; charset=UTF-8
Allow: GET, POST

<?xml version="1.0" encoding="utf-8"?>
<products xmlns="urn:com.example.products" 
          xmlns:xl="http://www.w3.org/1999/xlink">
  <product id="1234" xl:type="simple" 
           xl:href="http://example.com/products/1234">
    <name>Red Stapler</name>
    <price currency="EUR">3.14</price>
    <availability>false</availability>
  </product>
</products>

和 JSON 等价物（有点）：

HTTP/1.1 200 OK
Content-Type: application/vnd.com.myservice.v2+json; charset=UTF-8
Allow: GET, POST

[
  {
    id: "1234",
    links: [
      {
        rel: "self",
        href: "http://example.com/products/1234"
      }
    ],
    name: "Red Stapler",
    price: {
      currency: "EUR",
      value: 3.14
    },
    availability: false
  }
]

【问题讨论】：

+1 表示该演示文稿的链接（如果没有其他内容）。谢谢。

标签： json rest content-type http-1.1 hateoas

【解决方案1】：

您可以通过在内容类型中添加版本来实现版本控制：

application/vnd.acme.user-v1+xml

或者您也可以在 Accept 标头中使用限定符，这样您就不会触及您的内容类型：

application/vnd.acme.user+xml;v=1

您可以将内容类型application/vnd.acme.user+xml 拆分为两部分：第一部分 (application/vnd.acme.user) 描述媒体类型，第二部分 (xml) 描述响应格式。这意味着您可以使用其他格式，例如 json: application/vnd.acme.user+json。

在 HATEOAS 世界中，XML 在可读性和语义方面优于 JSON，如果您想使用 JSON，您可能会对以下规范感兴趣：https://github.com/kevinswiber/siren。

【讨论】：

谢谢。在决定限定符和新媒体类型时，您更喜欢哪一种来进行版本控制，为什么？
我会使用限定符来避免修改内容类型。我猜这只是口味问题。

【解决方案2】：

我所知道的最简洁的方法是使用配置文件。有一个 IETF RFC (RFC 6381)。

使用接受标头，指明您期望的响应类型。您仍然可以使用限定符。您可以要求遵守一个或多个以逗号分隔的配置文件，但如果您指定多个配置文件，则必须使用引号。

接受： 应用程序/json； profile="http://profiles.acme.com/user/v/1"

使用 content-type 标头，服务器可以做出类似的响应：

内容类型： 应用程序/json； profile="http://profiles.acme.com/user/v/1"

【讨论】：