使用XML和JSON内容类型版本化RESTful API

根据 this excellent presentation设计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
  }
]

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

application/vnd.acme.user-v1+xml

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

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

您可以将内容类型应用程序/ vnd.acme.user xml分为两部分：第一个(application / vnd.acme.user)描述媒体类型,第二个(xml)是响应的格式.这意味着您可以使用其他格式,如json：application / vnd.acme.user json.

在HATEOAS世界中,XML的可读性和语义目的要优于JSON,如果要使用JSON,您可能对此规范感兴趣：https://github.com/kevinswiber/siren.

使用XML和JSON内容类型版本化RESTful API

相关文章