RFC 7089
HTTP Framework for Time-Based Access to Resource States -- Memento
Pages: 50
Informational
Informational
Part 3 of 3 – Pages 36 to 50
5. TimeMaps: Content and Serialization
A TimeMap is introduced to support retrieving a comprehensive list of all Mementos for a specific Original Resource known to a server. The entity-body of a response to an HTTP GET request issued against a TimeMap's URI-T: o MUST list the URI-R of the Original Resource that the TimeMap is about; o MUST list the URI-M and archival datetime of each Memento for the Original Resource known to the server, preferably in a single document, or, alternatively in multiple documents that can be gathered by following contained links with a "timemap" Relation Type; o SHOULD list the URI-G of one or more TimeGates for the Original Resource known to the responding server; o SHOULD, for self-containment, list the URI-T of the TimeMap itself; o MUST unambiguously type listed resources as being Original Resource, TimeGate, Memento, or TimeMap. The entity-body of a response from a TimeMap MAY be serialized in various ways, but the link-value format serialization described here MUST be supported. In this serialization, the entity-body MUST be formatted in the same way as the value of an HTTP "Link" header, and hence MUST comply to the "link-value" construction rule of Section 5. The Link header field of [RFC5988], and the media type of the entity- body MUST be "application/link-format" as introduced in [RFC6690]. Links contained in the entity-body MUST be interpreted as follows: o The Context IRI is set to the anchor parameter, when specified; o The Context IRI of links with the "self" Relation Types is the URI-T of the TimeMap, i.e., the URI of the resource from which the TimeMap was requested; o The Context IRI of all other links is the URI-R of the Original Resource, which is provided as the Target IRI of the link with an "original" Relation Type. In order to retrieve the link-value serialization of a TimeMap, a user agent uses an "Accept" request header with a value set to "application/link-format". This is shown in Figure 27.
GET /timemap/http://a.example.org/ HTTP/1.1 Host: arxiv.example.net Accept: application/link-format;q=1.0 Connection: close Figure 27: Request for a TimeMap If the TimeMap requested by the user agent exists, the server's response has a "200 OK" HTTP status code and the list of Mementos is provided in the entity-body of the response. Such a response is shown in Figure 28. 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/", ... Figure 28: Response from a TimeMap
5.1. Special Cases
5.1.1. Index and Paging TimeMaps
Cases exist in which a TimeMap points at one or more other TimeMaps: o Index TimeMap - A TimeMap can merely point at other TimeMaps and not list any Mementos itself. This can happen when Mementos are spread across several archives that share a front-end. An example is shown in Figure 29. o Paging TimeMap - The number of available Mementos can require introducing multiple TimeMaps that can be paged. An example is shown in Figure 30. Note that a Paging TimeMap contains links to other TimeMaps but actually also lists Mementos. In both cases, including the "from" and "until" attributes for "timemap" links is RECOMMENDED as a means to express the temporal span of Mementos listed in each TimeMap. Note that TimeMaps obtained by following a "timemap" link can contain links to further TimeMaps. <http://a.example.org>;rel="original", <http://arxiv.example.net/timegate/http://a.example.org> ; rel="timegate", <http://arxiv.example.net/timemap/http://a.example.org> ; rel="self";type="application/link-format", <http://arxiv1.example.net/timemap/http://a.example.org> ; rel="timemap";type="application/link-format" ; from="Wed, 21 Jun 2000 04:41:56 GMT" ; until="Wed, 09 Apr 2008 20:30:51 GMT", <http://arxiv2.example.net/timemap/http://a.example.org> ; rel="timemap";type="application/link-format" ; from="Thu, 10 Apr 2008 20:30:51 GMT" ; until="Tue, 27 Oct 2009 20:49:54 GMT", <http://arxiv3.example.net/timemap/http://a.example.org> ; rel="timemap";type="application/link-format" ; from="Thu, 29 Oct 2009 20:30:51 GMT" Figure 29: Index TimeMap
<http://a.example.org>;rel="original", <http://arxiv.example.net/timegate/http://a.example.org> ; rel="timegate", <http://arxiv.example.net/timemap/1/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/timemap/2/http://a.example.org> ; rel="timemap";type="application/link-format" ; from="Thu, 10 Apr 2008 20:30:51 GMT" ; until="Tue, 27 Oct 2009 20:49:54 GMT", <http://arxiv.example.net/timemap/3/http://a.example.org> ; rel="timemap";type="application/link-format" ; from="Thu, 29 Oct 2009 20:30:51 GMT" ; until="Fri, 31 Aug 2012 12:22:34 GMT" <http://arxiv.example.net/web/20000620180259/http://a.example.org> ; rel="memento";datetime="Tue, 20 Jun 2000 18:02:59 GMT", <http://arxiv.example.net/web/20000621011731/http://a.example.org> ; rel="memento";datetime="Wed, 21 Jun 2000 01:17:31 GMT", <http://arxiv.example.net/web/20000621044156/http://a.example.org> ; rel="memento";datetime="Wed, 21 Jun 2000 04:41:56 GMT", ... Figure 30: Paging TimeMap5.1.2. Mementos for TimeMaps
A TimeMap itself can act as an Original Resource for which a TimeGate and Mementos may exist. Hence, the response from a TimeMap could include a "timegate" link to a TimeGate via which prior TimeMap versions are available. And, in cases where URI-T=URI-R=URI-G (a TimeMap is an Original Resource that acts as its own TimeGate), an "original" link pointing at the TimeMap URI-T would be included. Therefore, caution is required in cases where a TimeMap for an Original Resource wants to explicitly express in a "Link" header for which Original Resource it is a TimeMap. It can do so by including a "timemap" link that has the URI-R of the Original Resource as Context IRI and the URI-T of the TimeMap as Target IRI. Figure 31 shows the response to an HTTP HEAD request against a TimeMap that has http://arxiv.example.net/timemap/http://a.example.org as URI-T. This TimeMap provides information about Mementos for the Original Resource that has http://a.example.org as URI-R. The response includes an "original" link pointing to the Original Resource that this TimeMap is about. Note the use of the "anchor" attribute in this link to convey the URI-R of that Original Resource.
HTTP/1.1 200 OK Date: Thu, 21 Jan 2010 00:06:50 GMT Server: Apache Link: <http://arxiv.example.net/timemap/http://a.example.org> ; anchor="http://a.example.org"; rel="timemap" ; type="application/link-format" Content-Length: 0 Content-Type: application/link-format; charset=UTF-8 Connection: close Figure 31: TimeMap Links to the Original Resource It Is about6. IANA Considerations
6.1. HTTP Headers
IANA has registered the "Accept-Datetime" and "Memento-Datetime" HTTP headers (defined in Section 2.1.1) in the "Permanent Message Header Field Names" registry: o Header field name: Accept-Datetime o Applicable protocol: "http" (RFC 2616) o Status: informational o Author/Change controller: Herbert Van de Sompel, Los Alamos National Laboratory, hvdsomp@gmail.com o Specification document(s): this document o Header field name: Memento-Datetime o Applicable protocol: "http" (RFC 2616) o Status: informational o Author/Change controller: Herbert Van de Sompel, Los Alamos National Laboratory, hvdsomp@gmail.com o Specification document(s): this document6.2. Link Relation Types
IANA has registered the Relation Types "original", "timegate", "timemap", and "memento" (defined in Section 2.2) in the "Link Relation Types" registry: o Relation Name: original o Description: The Target IRI points to an Original Resource. o Reference: this document o Notes: An Original Resource is a resource that exists or used to exist, and for which access to one of its prior states may be required.
o Relation Name: timegate
o Description: The Target IRI points to a TimeGate for an Original
Resource.
o Reference: this document
o Notes: A TimeGate for an Original Resource is a resource that is
capable of datetime negotiation to support access to prior states
of the Original Resource.
o Relation Name: timemap
o Description: The Target IRI points to a TimeMap for an Original
Resource.
o Reference: this document
o Notes: A TimeMap for an Original Resource is a resource from which
a list of URIs of Mementos of the Original Resource is available.
o Relation Name: memento
o Description: The Target IRI points to a Memento, a fixed resource
that will not change state anymore.
o Reference: this document
o Notes: A Memento for an Original Resource is a resource that
encapsulates a prior state of the Original Resource.
7. Security Considerations
Provision of a "timegate" HTTP "Link" header in responses to requests
for an Original Resource that is protected (e.g., 401 or 403 HTTP
response codes) is OPTIONAL. The inclusion of this Link when
requesting authentication is at the server's discretion; cases may
exist in which a server protects the current state of a resource, but
supports open access to prior states and thus chooses to supply this
HTTP "Link" header. Conversely, the server may choose to not
advertise the TimeGate URIs (e.g., they exist in an intranet archive)
for unauthenticated requests.
The veracity of archives and the relationships between Original
Resources and Mementos is beyond the scope of this document. Even in
the absence of malice, it is possible for separate archives to have
different Mementos for the same Original Resource at the same
datetime if the state of the Original Resource was dependent on the
requesting archive's user agent IP address, specific HTTP request
headers, and possibly other factors.
Further authentication, encryption, and other security-related issues
are otherwise orthogonal to Memento.
8. Acknowledgements
The Memento effort is funded by the Library of Congress. Many thanks to Kris Carpenter Negulescu, Michael Hausenblas, Erik Hetzner, Larry Masinter, Gordon Mohr, David Rosenthal, Ed Summers, James Anderson, Tim Starling, Martin Klein, and Mark Nottingham for feedback. Many thanks to Samuel Adams, Scott Ainsworth, Lyudmilla Balakireva, Frank McCown, Harihar Shankar, Brad Tofel, Andrew Jackson, Ahmed Alsum, Mat Kelly, and Ilya Kreymer for implementations that informed the specification.9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC5829] Brown, A., Clemm, G., and J. Reschke, "Link Relation Types for Simple Version Navigation between Web Resources", RFC 5829, April 2010. [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, August 2012. [RFC6903] Snell, J., "Additional Link Relation Types", RFC 6903, March 2013.9.2. Informative References
[DATED-URI] Masinter, L., "The 'tdb' and 'duri' URI schemes, based on dated URIs", Work in Progress, January 2012. [Fitch] Fitch, K., "Web site archiving - an approach to recording every materially different response produced by a website", July 2003, <http://ausweb.scu.edu.au/aw03/papers/fitch/paper.html>. [RFC1123] Braden, R., "Requirements for Internet Hosts - Application and Support", STD 3, RFC 1123, October 1989.
[W3C.REC-aww-20041215] Jacobs, I. and N. Walsh, "Architecture of the World Wide Web", December 2004, <http://www.w3.org/TR/webarch/>. [W3C.gen-ont-20090420] Berners-Lee, T., "Architecture of the World Wide Web", April 2009, <http://www.w3.org/2006/gen/ont>.
Appendix A. Use of Headers and Relation Types per Pattern
+-----------------+-----------------+----------+----------+---------+ | Response Header | Pattern | Original | TimeGate | Memento | | | | Resource | | | +-----------------+-----------------+----------+----------+---------+ | Vary: | Pattern 1.1 | 1 | 1 | 0 | | accept-datetime | (Section 4.1.1) | | | | | | & | | | | | | Pattern 1.2 | | | | | | (Section 4.1.2) | | | | | | | | | | | | Pattern 1.3 | 1 | 1 | 1 | | | (Section 4.1.3) | | | | | | | | | | | | Pattern 2.1 | 0 | 1 | 0 | | | (Section 4.2.1) | | | | | | & | | | | | | Pattern 2.2 | | | | | | (Section 4.2.2) | | | | | | | | | | | | Pattern 2.3 | 0 | 1 | 1 | | | (Section 4.2.3) | | | | | | | | | | | | Pattern 3 | 1 | NA | 1 | | | (Section 4.3) | | | | | | | | | | | | Pattern 4 | 0 | NA | 1 | | | (Section 4.4) | | | | +-----------------+-----------------+----------+----------+---------+ (cont.)
+-----------------+-----------------+----------+----------+---------+ | Response Header | Pattern | Original | TimeGate | Memento | | | | Resource | | | +-----------------+-----------------+----------+----------+---------+ | Vary: | | | | | | Memento- | Pattern 1.1 | 0 | 0 | 1 | | Datetime | (Section 4.1.1) | | | | | | & | | | | | | Pattern 1.2 | | | | | | (Section 4.1.2) | | | | | | | | | | | | Pattern 1.3 | 1 | 1 | 1 | | | (Section 4.1.3) | | | | | | | | | | | | Pattern 2.1 | 0 | 0 | 1 | | | (Section 4.2.1) | | | | | | & | | | | | | Pattern 2.2 | | | | | | (Section 4.2.2) | | | | | | | | | | | | Pattern 2.3 | 0 | 1 | 1 | | | (Section 4.2.3) | | | | | | | | | | | | Pattern 3 | 1 | NA | 1 | | | (Section 4.3) | | | | | | | | | | | | Pattern 4 | 0 | NA | 1 | | | (Section 4.4) | | | | +-----------------+-----------------+----------+----------+---------+ (cont.)
+-----------------+-----------------+----------+----------+---------+ | Response Header | Pattern | Original | TimeGate | Memento | | | | Resource | | | +-----------------+-----------------+----------+----------+---------+ | Link: | | | | | | rel="original" | Pattern 1.1 | 0 | 1 | 1 | | | (Section 4.1.1) | | | | | | & | | | | | | Pattern 1.2 | | | | | | (Section 4.1.2) | | | | | | | | | | | | Pattern 1.3 | 1 | 1 | 1 | | | (Section 4.1.3) | | | | | | | | | | | | Pattern 2.1 | 0 | 1 | 1 | | | (Section 4.2.1) | | | | | | & | | | | | | Pattern 2.2 | | | | | | (Section 4.2.2) | | | | | | | | | | | | Pattern 2.3 | 0 | 1 | 1 | | | (Section 4.2.3) | | | | | | | | | | | | Pattern 3 | 1 | NA | 1 | | | (Section 4.3) | | | | | | | | | | | | Pattern 4 | 0 | NA | 1 | | | (Section 4.4) | | | | +-----------------+-----------------+----------+----------+---------+ (cont.)
+-----------------+-----------------+----------+----------+---------+ | Response Header | Pattern | Original | TimeGate | Memento | | | | Resource | | | +-----------------+-----------------+----------+----------+---------+ | Link: | | | | | | rel="timegate" | Pattern 1.1 | >=0 | >=0 | >=0 | | | (Section 4.1.1) | | | | | | & | | | | | | Pattern 1.2 | | | | | | (Section 4.1.2) | | | | | | | | | | | | Pattern 1.3 | >=0 | >=0 | >=0 | | | (Section 4.1.3) | | | | | | | | | | | | Pattern 2.1 | >=0 | 0 | >=0 | | | (Section 4.2.1) | | | | | | & | | | | | | Pattern 2.2 | | | | | | (Section 4.2.2) | | | | | | | | | | | | Pattern 2.3 | >=0 | >=0 | >=0 | | | (Section 4.2.3) | | | | | | | | | | | | Pattern 3 | NA | NA | NA | | | (Section 4.3) | | | | | | | | | | | | Pattern 4 | NA | NA | NA | | | (Section 4.4) | | | | +-----------------+-----------------+----------+----------+---------+ (cont.)
+-----------------+-----------------+----------+----------+---------+
| Response Header | Pattern | Original | TimeGate | Memento |
| | | Resource | | |
+-----------------+-----------------+----------+----------+---------+
| Link: | | | | |
| rel="timemap" | Pattern 1.1 | >=0 | >=0 | >=0 |
| | (Section 4.1.1) | | | |
| | & | | | |
| | Pattern 1.2 | | | |
| | (Section 4.1.2) | | | |
| | | | | |
| | Pattern 1.3 | >=0 | >=0 | >=0 |
| | (Section 4.1.3) | | | |
| | | | | |
| | Pattern 2.1 | >=0 | >=0 | >=0 |
| | (Section 4.2.1) | | | |
| | & | | | |
| | Pattern 2.2 | | | |
| | (Section 4.2.2) | | | |
| | | | | |
| | Pattern 2.3 | >=0 | >=0 | >=0 |
| | (Section 4.2.3) | | | |
| | | | | |
| | Pattern 3 | >=0 | NA | >=0 |
| | (Section 4.3) | | | |
| | | | | |
| | Pattern 4 | >=0 | NA | >=0 |
| | (Section 4.4) | | | |
| | | | | |
+-----------------+-----------------+----------+----------+---------+
(cont.)
+-----------------+-----------------+----------+----------+---------+ | Response Header | Pattern | Original | TimeGate | Memento | | | | Resource | | | +-----------------+-----------------+----------+----------+---------+ | Link: | | | | | | rel="memento" | Pattern 1.1 | >=0 | >=0 | >=0 | | | (Section 4.1.1) | | | | | | & | | | | | | Pattern 1.2 | | | | | | (Section 4.1.2) | | | | | | | | | | | | Pattern 1.3 | >=0 | >=0 | >=0 | | | (Section 4.1.3) | | | | | | | | | | | | Pattern 2.1 | >=0 | >=0 | >=0 | | | (Section 4.2.1) | | | | | | & | | | | | | Pattern 2.2 | | | | | | (Section 4.2.2) | | | | | | | | | | | | Pattern 2.3 | >=0 | >=0 | >=0 | | | (Section 4.2.3) | | | | | | | | | | | | Pattern 3 | >=0 | NA | >=0 | | | (Section 4.3) | | | | | | | | | | | | Pattern 4 | >=0 | NA | >=0 | | | (Section 4.4) | | | | +-----------------+-----------------+----------+----------+---------+ Table 5: Memento Headers
Authors' Addresses
Herbert Van de Sompel Los Alamos National Laboratory PO Box 1663 Los Alamos, New Mexico 87545 USA Phone: +1 505 667 1267 EMail: hvdsomp@gmail.com URI: http://public.lanl.gov/herbertv/ Michael Nelson Old Dominion University Norfolk, Virginia 23529 USA Phone: +1 757 683 6393 EMail: mln@cs.odu.edu URI: http://www.cs.odu.edu/~mln/ Robert Sanderson Los Alamos National Laboratory PO Box 1663 Los Alamos, New Mexico 87545 USA Phone: +1 505 665 5804 EMail: azaroth42@gmail.com URI: http://public.lanl.gov/rsanderson/