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

Question

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

Answer 1

RFC5829 描述了 version history 但没有建议 return 格式。

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

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

所以你真正想要的是 return collection of links。对此的最佳表示是 another question

RFC7089 - HTTP Framework for Time-Based Access to Resource States - Memento describes a similar thing called a time-map and suggests using 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 中用于 link header 本身的 link 的格式相同，但删除了空格（与上面的示例相反！） .

link-format 对 API 客户来说可能比 JSON 更陌生，因此您可以考虑 return 通过 [=] 获取某种 JSON 文档43=]谈判。在 JSON 中表示 link 的 collection 没有标准格式（或者更确切地说，有几个具有不同优势和劣势的竞争标准）。一个合理的概述是 Mark Nottingham's blog。虽然这在撰写本文时已经过时，但他提到的格式仍然是您搜索建议时会遇到的格式。一个好的建议可能是 HAL+JSON。请参阅 wikipedia and the draft RFC（注意草稿已过期，但 link 未过期）。使用这个版本历史看起来像：

{
  "_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 格式（这是我个人的偏好）。

对于此处建议的两种格式，您可能需要仔细考虑要使用的关系名称 - 请参阅 https://whosebug.com/q/59176515/1569204

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

What is an appropriate format for returning version-history of a resource via http

rest

version-control

http

rfc