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

问题

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?

回答1:

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

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

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"  }
  }
}

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

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?

来源：https://stackoverflow.com/questions/59268948/what-is-an-appropriate-format-for-returning-version-history-of-a-resource-via-ht

标签

rest

http

version-control

rfc