RFC 7089
HTTP Framework for Time-Based Access to Resource States -- Memento
Pages: 50
Informational
Informational
Part 1 of 3 – Pages 1 to 14
Independent Submission H. Van de Sompel Request for Comments: 7089 Los Alamos National Laboratory Category: Informational M. Nelson ISSN: 2070-1721 Old Dominion University R. Sanderson Los Alamos National Laboratory December 2013 HTTP Framework for Time-Based Access to Resource States -- MementoAbstract
The HTTP-based Memento framework bridges the present and past Web. It facilitates obtaining representations of prior states of a given resource by introducing datetime negotiation and TimeMaps. Datetime negotiation is a variation on content negotiation that leverages the given resource's URI and a user agent's preferred datetime. TimeMaps are lists that enumerate URIs of resources that encapsulate prior states of the given resource. The framework also facilitates recognizing a resource that encapsulates a frozen prior state of another resource. Status of This Memo This document is not an Internet Standards Track specification; it is published for informational purposes. This is a contribution to the RFC Series, independently of any other RFC stream. The RFC Editor has chosen to publish this document at its discretion and makes no statement about its value for implementation or deployment. Documents approved for publication by the RFC Editor are not a candidate for any level of Internet Standard; see Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7089.
Copyright Notice Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.Table of Contents
1. Introduction ....................................................4 1.1. Terminology ................................................4 1.2. Notational Conventions .....................................4 1.3. Purpose ....................................................5 2. HTTP Headers, Link Relation Types ...............................7 2.1. HTTP Headers ...............................................7 2.1.1. Accept-Datetime and Memento-Datetime ................7 2.1.2. Vary ................................................8 2.1.3. Link ................................................8 2.2. Link Relation Types ........................................9 2.2.1. Link Relation Type "original" .......................9 2.2.2. Link Relation Type "timegate" .......................9 2.2.3. Link Relation Type "timemap" ........................9 2.2.4. Link Relation Type "memento" .......................10 3. Overview of the Memento Framework ..............................11 3.1. Datetime Negotiation ......................................11 3.2. TimeMaps ..................................................13 4. Datetime Negotiation: HTTP Interactions ........................14 4.1. Pattern 1 - The Original Resource Acts as Its Own TimeGate ..................................................15 4.1.1. Pattern 1.1 - URI-R=URI-G; 302-Style Negotiation; Distinct URI-M for Mementos ..........16 4.1.2. Pattern 1.2 - URI-R=URI-G; 200-Style Negotiation; Distinct URI-M for Mementos ...........18 4.1.3. Pattern 1.3 - URI-R=URI-G; 200-Style Negotiation; No Distinct URI-M for Mementos ........19 4.2. Pattern 2 - A Remote Resource Acts as a TimeGate for the Original Resource .................................20 4.2.1. Pattern 2.1 - URI-R<>URI-G; 302-Style Negotiation; Distinct URI-M for Mementos ...........22 4.2.2. Pattern 2.2 - URI-R<>URI-G; 200-Style Negotiation; Distinct URI-M for Mementos ...........24 4.2.3. Pattern 2.3 - URI-R<>URI-G; 200-Style Negotiation; No Distinct URI-M for Mementos ........25
4.3. Pattern 3 - The Original Resource is a Fixed Resource .....26
4.4. Pattern 4 - Mementos without a TimeGate ...................27
4.5. Special Cases .............................................29
4.5.1. Original Resource Provides No "timegate" Link ......29
4.5.2. Server Exists but Original Resource No
Longer Does ........................................29
4.5.3. Issues with Accept-Datetime ........................30
4.5.4. Memento of a 3XX Response ..........................30
4.5.5. Memento of Responses with 4XX or 5XX HTTP
Status Codes .......................................32
4.5.6. Sticky "Memento-Datetime" and "original"
Link for Mementos ..................................33
4.5.7. Intermediate Resources .............................34
4.5.8. Resources Excluded from Datetime Negotiation .......35
5. TimeMaps: Content and Serialization ............................36
5.1. Special Cases .............................................38
5.1.1. Index and Paging TimeMaps ..........................38
5.1.2. Mementos for TimeMaps ..............................39
6. IANA Considerations ............................................40
6.1. HTTP Headers ..............................................40
6.2. Link Relation Types .......................................40
7. Security Considerations ........................................41
8. Acknowledgements ...............................................42
9. References .....................................................42
9.1. Normative References ......................................42
9.2. Informative References ....................................42
Appendix A. Use of Headers and Relation Types per Pattern .........43
1. Introduction
1.1. Terminology
This specification uses the terms "resource", "request", "response", "entity-body", "content negotiation", "user agent", and "server" as described in [RFC2616], and it uses the terms "representation" and "resource state" as described in [W3C.REC-aww-20041215]. In addition, the following terms specific to the Memento framework are introduced: o Original Resource: 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 Memento: A Memento for an Original Resource is a resource that encapsulates a prior state of the Original Resource. A Memento for an Original Resource as it existed at time T is a resource that encapsulates the state the Original Resource had at time T. o TimeGate: 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 TimeMap: A TimeMap for an Original Resource is a resource from which a list of URIs of Mementos of the Original Resource is available.1.2. Notational Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. When needed for extra clarity, the following conventions are used: o URI-R is used to denote the URI of an Original Resource. o URI-G is used to denote the URI of a TimeGate. o URI-M is used to denote the URI of a Memento. o URI-T is used to denote the URI of a TimeMap.
1.3. Purpose
The state of an Original Resource may change over time. Dereferencing its URI at any specific moment yields a response that reflects the resource's state at that moment: a representation of the resource's state (e.g., "200 OK" HTTP status code), an indication of its nonexistence (e.g., "404 Not Found" HTTP status code), a relation to another resource (e.g., "302 Found" HTTP status code), etc. However, responses may also exist that reflect prior states of an Original Resource: a representation of a prior state of the Original Resource, an indication that the Original Resource did not exist at some time in the past, a relation that the Original Resource had to another resource at some time in the past, etc. Mementos that provide such responses exist in Web archives, content management systems, or revision control systems, among others. For any given Original Resource several Mementos may exist, each one reflecting a frozen prior state of the Original Resource. Examples are: Mementos for Original Resource http://www.ietf.org/ are as follows: o http://web.archive.org/web/19970107171109/http://www.ietf.org/ o http://webarchive.nationalarchives.gov.uk/20080906200044/http:// www.ietf.org/ Mementos for Original Resource http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol are as follows: o http://en.wikipedia.org/w/ index.php?title=Hypertext_Transfer_Protocol&oldid=366806574 o http://en.wikipedia.org/w/ index.php?title=Hypertext_Transfer_Protocol&oldid=33912 o http://web.archive.org/web/20071011153017/http://en.wikipedia.org/ wiki/Hypertext_Transfer_Protocol Mementos for Original Resource http://www.w3.org/TR/webarch/ are as follows: o http://www.w3.org/TR/2004/PR-webarch-20041105/ o http://www.w3.org/TR/2002/WD-webarch-20020830/ o http://archive.is/20120527002537/http://www.w3.org/TR/webarch/
In the abstract, the Memento framework introduces a mechanism to
access versions of Web resources that:
o Is fully distributed in the sense that resource versions may
reside on multiple servers, and that any such server is likely
only aware of the versions it holds;
o Uses the global notion of datetime as a resource version indicator
and access key;
o Leverages the following primitives of [W3C.REC-aww-20041215]:
resource, resource state, representation, content negotiation, and
link.
The core components of Memento's mechanism to access resource
versions are:
1. The abstract notion of the state of an Original Resource (URI-R)
as it existed at datetime T. Note the relationship with the
ability to identify the state of a resource at datetime T by
means of a URI as intended by the proposed Dated URI scheme
[DATED-URI].
2. A "bridge" from the present to the past, consisting of:
o The existence of a TimeGate (URI-G), which is aware of (at
least part of the) version history of the Original Resource
(URI-R);
o The ability to negotiate in the datetime dimension with that
TimeGate (URI-G), as a means to access the state that the
Original Resource (URI-R) had at datetime T.
3. A "bridge" from the past to the present, consisting of an
appropriately typed link from a Memento (URI-M), which
encapsulates the state the Original Resource (URI-R) had at
datetime T, to the Original Resource (URI-R).
4. The existence of a TimeMap (URI-T) from which a list of all
Mementos that encapsulate a prior state of the Original Resource
(URI-R) can be obtained.
This document is concerned with specifying an instantiation of these
abstractions for resources that are identified by HTTP(S) URIs.
2. HTTP Headers, Link Relation Types
The Memento framework is concerned with HEAD and GET interactions with Original Resources, TimeGates, Mementos, and TimeMaps that are identified by HTTP or HTTPS URIs. Details are only provided for resources identified by HTTP URIs but apply similarly to those with HTTPS URIs.2.1. HTTP Headers
The Memento framework operates at the level of HTTP request and response headers. It introduces two new headers ("Accept-Datetime" and "Memento-Datetime") and introduces new values for two existing headers ("Vary" and "Link"). Other HTTP headers are present or absent in Memento response/request cycles as specified by [RFC2616].2.1.1. Accept-Datetime and Memento-Datetime
The "Accept-Datetime" request header is transmitted by a user agent to indicate it wants to access a past state of an Original Resource. To that end, the "Accept-Datetime" header is conveyed in an HTTP request issued against a TimeGate for an Original Resource, and its value indicates the datetime of the desired past state of the Original Resource. Example of an "Accept-Datetime" request header: Accept-Datetime: Thu, 31 May 2007 20:35:00 GMT The "Memento-Datetime" response header is used by a server to indicate that a response reflects a prior state of an Original Resource. Its value expresses the datetime of that state. The URI of the Original Resource for which the response reflects a prior state is provided as the Target IRI of a link provided in the HTTP "Link" header that has a Relation Type of "original" (see Section 2.2). The presence of a "Memento-Datetime" header and associated value for a given response constitutes a promise that the resource state reflected in the response will no longer change (see Section 4.5.6). Example of a "Memento-Datetime" response header: Memento-Datetime: Wed, 30 May 2007 18:47:52 GMT Values for the "Accept-Datetime" and "Memento-Datetime" headers consist of a MANDATORY datetime expressed according to the [RFC1123] format, which is formalized by the rfc1123-date construction rule of
the BNF in Figure 1. This BNF is derived from the HTTP-date construction of the BNF for Full Dates provided in [RFC2616]. The datetime is case sensitive with names for days and months exactly as shown in the wkday and month construction rules of the BNF, respectively. The datetime MUST be represented in Greenwich Mean Time (GMT). accept-dt-value = rfc1123-date rfc1123-date = wkday "," SP date1 SP time SP "GMT" date1 = 2DIGIT SP month SP 4DIGIT ; day month year (e.g., 20 Mar 1957) time = 2DIGIT ":" 2DIGIT ":" 2DIGIT ; 00:00:00 - 23:59:59 (e.g., 14:33:22) wkday = "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" | "Sun" month = "Jan" | "Feb" | "Mar" | "Apr" | "May" | "Jun" | "Jul" | "Aug" | "Sep" | "Oct" | "Nov" | "Dec" Figure 1: BNF for the Datetime Format2.1.2. Vary
Generally, the "Vary" header is used in HTTP responses to indicate the dimensions in which content negotiation is possible. In the Memento framework, a TimeGate uses the "Vary" header with a value that includes "accept-datetime" to convey that datetime negotiation is possible. For example, this use of the "Vary" header indicates that datetime is the only dimension in which negotiation is possible: Vary: accept-datetime The use of the "Vary" header in this example shows that both datetime negotiation and media type content negotiation are possible: Vary: accept-datetime, accept2.1.3. Link
The Memento framework defines the "original", "timegate", "timemap", and "memento" Relation Types to convey typed links among Original Resources, TimeGates, Mementos, and TimeMaps. They are defined in Section 2.2, below. In addition, existing Relation Types may be used, for example, to support navigating among Mementos. Examples are "first", "last", "prev", "next", "predecessor-version", and "successor-version" as detailed in [RFC5988] and [RFC5829].
2.2. Link Relation Types
This section introduces the Relation Types used in the Memento framework. They are defined in a general way, and their use in HTTP "Link" headers [RFC5988] is described in detail. The use of these Relation Types in TimeMaps is described in Section 5.2.2.1. Link Relation Type "original"
"original" -- A link with an "original" Relation Type is used to point from a TimeGate or a Memento to its associated Original Resource. Use in HTTP "Link" headers: Responses to HTTP HEAD/GET requests issued against a TimeGate or a Memento MUST include exactly one link with an "original" Relation Type in their HTTP "Link" header.2.2.2. Link Relation Type "timegate"
"timegate" -- A link with a "timegate" Relation Type is used to point from the Original Resource, as well as from a Memento associated with the Original Resource, to a TimeGate for the Original Resource. Use in HTTP "Link" headers: If there is a TimeGate associated with an Original Resource or Memento that is preferred for use, then responses to HTTP HEAD/GET requests issued against these latter resources MUST include a link with a "timegate" Relation Type in their HTTP "Link" header. Since multiple TimeGates can exist for any Original Resource, multiple "timegate" links MAY occur, each with a distinct Target IRI.2.2.3. Link Relation Type "timemap"
"timemap" -- A link with a "timemap" Relation Type is used to point from a TimeGate or a Memento associated with an Original Resource, as well as from the Original Resource itself, to a TimeMap for the Original Resource. Attributes: A link with a "timemap" Relation Type SHOULD use the "type" attribute to convey the MIME type of the TimeMap serialization. The "from" and "until" attributes may be used to express the start and end of the temporal interval covered by Mementos listed in the TimeMap. That is, the linked TimeMap will not contain Mementos with archival datetimes outside of the expressed temporal interval. Attempts SHOULD be made to convey this interval as accurately as possible. The value for the these attributes MUST
be a datetime expressed according to the rfc1123-date construction rule of the BNF in Figure 1, and it MUST be represented in Greenwich Mean Time (GMT). Use in HTTP "Link" headers: If there is a TimeMap associated with an Original Resource, a TimeGate, or a Memento that is preferred for use, then responses to HTTP HEAD/GET requests issued against these latter resources MUST include a link with a "timemap" Relation Type in their HTTP "Link" header. Multiple such links, each with a distinct Target IRI, MAY be expressed as a means to point to different TimeMaps or to different serializations of the same TimeMap. In all cases, use of the "from" and "until" attributes is OPTIONAL.2.2.4. Link Relation Type "memento"
"memento" -- A link with a "memento" Relation Type is used to point from a TimeGate or a Memento for an Original Resource, as well as from the Original Resource itself, to a Memento for the Original Resource. Attributes: A link with a "memento" Relation Type MUST include a "datetime" attribute with a value that matches the "Memento-Datetime" of the Memento that is the target of the link; that is, the value of the "Memento-Datetime" header that is returned when the URI of the linked Memento is dereferenced. The value for the "datetime" attribute MUST be a datetime expressed according to the rfc1123-date construction rule of the BNF in Figure 1, and it MUST be represented in Greenwich Mean Time (GMT). This link MAY include a "license" attribute to associate a license with the Memento; the value for the "license" attribute MUST be a URI. Use in HTTP "Link" headers: Responses to HTTP HEAD/GET requests issued against an Original Resource, a TimeGate, and a Memento MAY include links in their HTTP "Link" headers with a "memento" Relation Type. For responses in which a Memento is selected, the provision of navigational links that lead to Mementos other than the selected one can be beneficial to the user agent. Of special importance are links that lead to the temporally first and last Memento known to the responding server, as well as links leading to Mementos that are temporally adjacent to the selected one.
3. Overview of the Memento Framework
The Memento framework defines two complementary approaches to support obtaining representations of prior states of an Original Resource: o Datetime Negotiation: Datetime negotiation is a variation on content negotiation by which a user agent expresses a datetime preference pertaining to the representation of an Original Resource, instead of, for example, a media type preference. Based on the responding server's knowledge of the past of the Original Resource, it selects a Memento of the Original Resource that best meets the user agent's datetime preference. An overview is provided in Section 3.1; details are in Section 4. o TimeMaps: A TimeMap is a resource from which a list can be obtained that provides a comprehensive overview of the past of an Original Resource. A server makes a TimeMap available that enumerates all Mementos that the server is aware of, along with their archival datetime. A user agent can obtain the TimeMap and select Mementos from it. An overview is provided in Section 3.2; details are in Section 5.3.1. Datetime Negotiation
Figure 2 provides a schematic overview of a successful request/ response chain that involves datetime negotiation. Dashed lines depict HTTP transactions between user agent and server. The interactions are for a scenario where the Original Resource resides on one server, whereas both its TimeGate and Mementos reside on another (Pattern 2.1 (Section 4.2.1) in Section 4). Scenarios also exist in which all these resources are on the same server (for example, content management systems) or all are on different servers (for example, an aggregator of TimeGates). 1: UA --- HTTP HEAD/GET; Accept-Datetime: T ----------------> URI-R 2: UA <-- HTTP 200; Link: URI-G ----------------------------- URI-R 3: UA --- HTTP HEAD/GET; Accept-Datetime: T ----------------> URI-G 4: UA <-- HTTP 302; Location: URI-M; Vary; Link: URI-R,URI-T ------------------------------------------> URI-G 5: UA --- HTTP GET URI-M; Accept-Datetime: T ---------------> URI-M 6: UA <-- HTTP 200; Memento-Datetime: T; Link: URI-R,URI-T,URI-G ------------------------------------- URI-M Figure 2: A Datetime Negotiation Request/Response Chain
Step 1: The user agent that wants to access a prior state of the
Original Resource issues an HTTP HEAD/GET against URI-R that
has an "Accept-Datetime" HTTP header with a value of the
datetime of the desired state.
Step 2: The response from URI-R includes an HTTP "Link" header with
a Relation Type of "timegate" pointing at a TimeGate (URI-G)
for the Original Resource.
Step 3: The user agent starts the datetime negotiation process with
the TimeGate by issuing an HTTP GET request against URI-G
that has an "Accept-Datetime" HTTP header with a value of
the datetime of the desired prior state of the Original
Resource.
Step 4: The response from URI-G includes a "Location" header
pointing at a Memento (URI-M) for the Original Resource. In
addition, the response contains an HTTP "Link" header with a
Relation Type of "original" pointing at the Original
Resource (URI-R), and an HTTP "Link" header with a Relation
Type of "timemap" pointing at a TimeMap (URI-T).
Step 5: The user agent issues an HTTP GET request against URI-M.
Step 6: The response from URI-M includes a "Memento-Datetime" HTTP
header with a value of the archival datetime of the Memento.
It also contains an HTTP "Link" header with a Relation Type
of "original" pointing at the Original Resource (URI-R),
with a Relation Type of "timegate" pointing at a TimeGate
(URI-G) for the Original Resource, and with a Relation Type
of "timemap" pointing at a TimeMap (URI-T) for the Original
Resource. The state that is expressed by the response is
the state the Original Resource had at the archival datetime
expressed in the "Memento-Datetime" header.
In order to respond to a datetime negotiation request, the server
uses an internal algorithm to select the Memento that best meets the
user agent's datetime preference. The exact nature of the selection
algorithm is at the server's discretion but is intended to be
consistent, for example, always selecting the Memento that is nearest
in time relative to the requested datetime, always selecting the
Memento that is nearest in the past relative to the requested
datetime, etc.
Due to the sparseness of Mementos in most systems, the value of the
"Memento-Datetime" header returned by a server may differ
(significantly) from the value conveyed by the user agent in "Accept-
Datetime".
Although a Memento encapsulates a prior state of an Original Resource, the entity-body returned in response to an HTTP GET request issued against a Memento may very well not be byte-to-byte the same as an entity-body that was previously returned by that Original Resource. Various reasons exist why there are significant chances these would be different yet do convey substantially the same information. These include format migrations as part of a digital preservation strategy, URI-rewriting as applied by some Web archives, and the addition of banners as a means to brand Web archives. When negotiating in the datetime dimension, the regular content negotiation dimensions (media type, character encoding, language, and compression) remain available. It is the TimeGate server's responsibility to honor (or not) such content negotiation, and in doing so it MUST always first select a Memento that meets the user agent's datetime preference, and then consider honoring regular content negotiation for it. As a result of this approach, the returned Memento will not necessarily meet the user agent's regular content negotiation preferences. Therefore, it is RECOMMENDED that the server provides "memento" links in the HTTP "Link" header pointing at Mementos that do meet the user agent's regular content negotiation requests and that have a value for the "Memento-Datetime" header in the temporal vicinity of the user agent's preferred datetime value. A user agent that engages in datetime negotiation with a resource typically starts by issuing an HTTP HEAD, not GET, request with an "Accept-Datetime" header in order to determine how to proceed. This strategy is related to the existence of various server implementation patterns as will become clear in Section 4. Details about the HTTP interactions involved in datetime negotiation are provided in Section 4.3.2. TimeMaps
Figure 3 provides a schematic overview of a successful request/ response chain that shows a user agent obtaining a TimeMap. The pictorial conventions are the same as the ones used in Figure 2, as is the scenario. Note that, in addition to a TimeGate, an Original Resource and a Memento can also provide a link to a TimeMap.
1: UA --- HTTP HEAD/GET ------------------------------------> URI-R 2: UA <-- HTTP 200; Link: URI-G ----------------------------- URI-R 3: UA --- HTTP HEAD/GET ------------------------------------> URI-G 4: UA <-- HTTP 302; Location: URI-M; Vary; Link: URI-R,URI-T ------------------------------------------> URI-G 5: UA --- HTTP GET URI-T -----------------------------------> URI-T 6: UA <-- HTTP 200 ------------------------------------------ URI-T Figure 3: A Request/Response Chain to Obtain a TimeMap Step 1: The user agent that wants to access a TimeMap for the Original Resource issues an HTTP HEAD/GET against URI-R. This can be done with or without an "Accept-Datetime" HTTP header. Step 2: Irrespective of the use of an "Accept-Datetime" HTTP header in Step 1, the response from URI-R includes an HTTP "Link" header with a Relation Type of "timegate" pointing at a TimeGate (URI-G) for the Original Resource. Step 3: The user agent issues an HTTP GET request against URI-G. This can be done with or without an "Accept-Datetime" HTTP header. Step 4: Irrespective of the use of an "Accept-Datetime" HTTP header in Step 1, the response contains an HTTP "Link" header with a Relation Type of "timemap" pointing at a TimeMap (URI-T). Step 5: The user agent issues an HTTP GET request against URI-T. Step 6: The response from URI-T has an entity-body that lists all Mementos for the Original Resource known to the responding server, as well as their archival datetimes. Details about the content and serialization of TimeMaps are provided in Section 5.
(page 14 continued on part 2)