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

Question

根据设计RESTful接口的优秀演示,实现版本控制的首选方法是使用Accept-header,使用类似于:

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

这适用于XML Content-Types,但是可以使用相同的方案对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.

Answer 2

我知道最干净的方法是使用配置文件.有一个IETF RFC(RFC 6381).

使用accept标头,指出您期望的响应类型.您仍然可以使用限定符.您可以请求遵从一个或多个以逗号分隔的配置文件,但如果指定了多个配置文件,则必须使用引号.

接受: application/json; 型材= "http://profiles.acme.com/user/v/1"

使用内容类型标头,服务器可以响应相同:

Content-Type: application/json; 型材= "http://profiles.acme.com/user/v/1"