通过http返回资源的版本历史的适当格式是什么 [英] What is an appropriate format for returning version-history of a resource via http

问题描述

我正在设计一个ReSTful Web服务，该服务提供版本化的资源. 什么是返回版本历史的合适的返回格式(内容类型) ?

I am designing a ReSTful web service which provides a versioned resource. What is an appropriate return format (content-type) for returning a version history?

推荐答案

RFC5829描述了版本历史记录，但不建议返回格式.

RFC5829 describes a version history but does not suggest a return format.

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

First we assume you have a URL pointing to each version of the resource as in:

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

因此，您真正想要的是返回链接集合. 最好的表示方法是

So what you actually want is to return a collection of links. The best representation for this is another question

RFC7089-用于基于时间访问资源状态的HTTP框架-Memento 描述了类似的内容称为时间映射"的建议，并建议使用应用程序/链接格式(RFC6690) . 第36页:

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). An example of this is given on 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-format is just the same format for links used in http for the link header itself but with whitespace removed (contrary to the example above!).

链接格式对于API客户端而言可能比JSON更为陌生，因此您可以考虑通过内容类型协商返回某种JSON文档.没有用于表示JSON中的链接集合的标准格式(或者存在一些具有不同优缺点的竞争标准).合理的概述是马克·诺丁汉的博客.尽管在撰写本文时这已经很老了，但他提到的格式仍然是您搜索建议时会遇到的格式. 一个很好的建议可能是 HAL + JSON .请参见维基百科和

link-format may be more alien than JSON to API clients, so you might consider returning some kind of JSON document via content-type negotiation. There is no standard format for representing a collection of links in JSON (or rather there are several competing standards with different strengths and weaknesses). A reasonable overview is Mark Nottingham's blog. Though this is old at the time of writing, the formats he mentions are still the formats you will come across if you search for suggestions. A good suggestion might be HAL+JSON. See wikipedia and the draft RFC (note the draft is expired but the link is not). Using this a version history would look something like:

{
  "_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 格式(这是我的个人喜好).

I've added the datetime attribute here (possibly incorrectly) to represent a version time and used RFC3339 format (which is my personal preference).

对于此处建议的两种格式，您可能需要仔细考虑要使用的关系名称-请参见什么是合适的IANA关系名称?用于版本历史记录中的链接?

For both formats suggested here, you may want to consider carefully what relation names to use - see What is the appropriate IANA relation name to use for links in a version-history?

这篇关于通过http返回资源的版本历史的适当格式是什么的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！