什么是通过http返回资源的版本历史的适当格式

Question

我正在设计一个ReSTful Web服务，该服务提供版本化的资源。返回version history的适当返回格式（内容类型）是什么？

Answer 1

RFC5829描述了version history，但不建议返回格式。

首先，我们假设您有一个指向资源每个版本的URL，如下所示：

/path/to/resource/  - returns latest
/path/to/resource/v1 - returns version v1    
/path/to/resource/v2 - returns version v2

所以您真正想要的是返回链接集合。最好的表示法是another question

RFC7089 - HTTP Framework for Time-Based Access to Resource States - Memento描述了类似的内容，称为时间图，并建议使用application/link-format (RFC6690)。page 36上给出了一个示例：

   HTTP/1.1 200 OK
   Date: Thu, 21 Jan 2010 00:06:50 GMT
   Server: Apache
   Content-Length: 4883
   Content-Type: application/link-format
   Connection: close

    <http://a.example.org>;rel="original",
    <http://arxiv.example.net/timemap/http://a.example.org>
      ; rel="self";type="application/link-format"
      ; from="Tue, 20 Jun 2000 18:02:59 GMT"
      ; until="Wed, 09 Apr 2008 20:30:51 GMT",
    <http://arxiv.example.net/timegate/http://a.example.org>
      ; rel="timegate",
    <http://arxiv.example.net/web/20000620180259/http://a.example.org>
      ; rel="first memento";datetime="Tue, 20 Jun 2000 18:02:59 GMT"
      ; license="http://creativecommons.org/publicdomain/zero/1.0/",
    <http://arxiv.example.net/web/20091027204954/http://a.example.org>
       ; rel="last memento";datetime="Tue, 27 Oct 2009 20:49:54 GMT"
       ; license="http://creativecommons.org/publicdomain/zero/1.0/",
    <http://arxiv.example.net/web/20000621011731/http://a.example.org>
      ; rel="memento";datetime="Wed, 21 Jun 2000 01:17:31 GMT"
      ; license="http://creativecommons.org/publicdomain/zero/1.0/",
    <http://arxiv.example.net/web/20000621044156/http://a.example.org>
      ; rel="memento";datetime="Wed, 21 Jun 2000 04:41:56 GMT"
      ; license="http://creativecommons.org/publicdomain/zero/1.0/",
    ...

link-format与用于链接头本身的http中的链接格式相同，但删除了空格（与上面的示例相反！）。

链接格式对于API客户端而言可能比JSON更不适合，因此您可以考虑通过内容类型协商返回某种JSON文档。没有用于表示JSON中的链接集合的标准格式（或者存在一些具有不同优缺点的竞争标准）。合理的概述是Mark Nottingham's blog。尽管在撰写本文时这已经很老了，但他提到的格式仍然是您搜索建议时会遇到的格式。一个很好的建议可能是HAL + JSON。请参阅wikipedia和draft RFC（请注意草稿已过期，但链接未过期）。使用此版本历史记录看起来像：

{
  "_links": {
    "self": { "href": "/versions" },
    "first": { "href": "/foobar/version1", "datetime": "2019-01-01T12:00:00Z" },
    "memento": { "href": "/foobar/version2", "datetime": "2019-01-02T12:00:00Z"  }
    "latest": { "href": "/foobar/version3", "datetime": "2019-01-03T12:00:00Z"  }
  }
}

我在这里添加了datetime属性（可能不正确）以表示版本时间，并使用了RFC3339格式（这是我的个人喜好。）>

对于此处建议的两种格式，您可能需要仔细考虑要使用的关系名称-参见What is the appropriate IANA relation name to use for links in a version-history?