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

Question

根据this excellent presentation在设计 RESTful 接口(interface)时，实现版本控制的首选方法是利用 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
  }
]

Answer 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 .