 |
Memento Guide: |
About Guide Demos Tools |
| This document provides a detailed overview of the HTTP interactions involved in Memento. It considers various scenarios involving transactions with Original Resources, TimeGates and Mementos. Use this document alongside the Quick Start for Developers and the Introduction to Memento. |
A successful Memento HTTP interaction |
| The below picture illustrates the steps involved in a successful HTTP transaction flow in which a client uses the Accept-Datetime header to obtain a Memento URI-M for an Original Resource URI-R. Details of this flow are described in this document under scenarios [1], [2] Case 1, [3], [4] Case 5, [5], [6] Case 12. |
 |
Memento HTTP interactions for various scenarios |
| In the below transactions, values for the Accept-Datetime and Content-Datetime headers are datetimes expressed according to the RFC 1123 format referenced in Section
3.3.1 of RFC 2616 "Hypertext Transfer Protocol -- HTTP/1.1". |
| The Accept-Datetime header is used by a client to indicate it wants to retrieve
a representation of a past (not current) state of a resource. The value of the Accept-Datetime header indicates the datetime of the state of the resource the client is interested in. |
| The Content-Datetime header returned by a server
conveys the datetime of the state of a resource that corresponds with the returned representation. |
| It should be noted that in an HTTP transaction, the value of the Content-Datetime header returned by a server
may differ from the value conveyed by the client in Accept-Datetime, as representations for the requested datetime may not be available. |
| [1] |
The client goes into Memento mode by selecting a datetime.
The selected datetime is expressed in the Accept-Datetime header of the client's HTTP requests.
The client starts its navigation by issuing a HTTP HEAD against Original Resource URI-R
in order to find out whether URI-R has a TimeGate associated with it.
|
| [2] | The possible responses from the server that is the target of request [1] are listed below. |
| [2] Case 1 |
URI-R exists & server returns a "timegate" Link header pointing at TimeGate URI-G. Based on this information, the client can interact with this TimeGate in step [3]. 
|
| [2] Case 2 |
URI-R does not (no longer) exist & server returns a "timegate" Link header pointing at TimeGate URI-G. Based on this information, the client can interact with this TimeGate in step [3]. 
|
| [2] Case 3 |
URI-R exists & server does not return a "timegate" Link header pointing at a TimeGate. The client can still attempt to find Mementos for URI-R by interacting with a TimeGate of its choice, for example, configured in the client's preferences. The scenario continues with this chosen TimeGate in step [3]. 
|
| [2] Case 4 |
URI-R does not (no longer) exist & server does not return a "timegate" Link header pointing at a TimeGate. The client can still attempt to find Mementos for URI-R by interacting with a TimeGate of choice, for example, configured in the client's preferences. The scenario continues with this chosen TimeGate in step [3]. 
|
| [1] |
The client is not in Memento mode and hence does not select a datetime.
There is no Accept-Datetime header in the client's HTTP requests.
|
| [2] | The responses from the server that is the target of this request are exaclty the same as listed above under [2], Cases 1 through 4. The Link header pointing at a TimeGate should be provided unconditionally; it is not dependent on the existence of an Accept-Datetime request header. |
| [3] |
Client issues HTTP GET request with Accept-Datetime header against TimeGate URI-G for Original Resource URI-R.
In step [2], Cases 1 & 2 above, the URI-G of the TimeGate is obtained from the "timegate" Link header returned by the server of the Original Resource. In step [2], Cases 3 & 4, the URI-G of the TimeGate is the client's choice, for example, based on configured preferences. 
|
| [4] | TimeGate server that is the target of request [3] responds: |
| [4] Case 5 |
TimeGate server detects Accept-Datetime & URI-G exists & datetime can be parsed & datetime is in range for which server has Mementos for Original Resource URI-R. The TimeGate server provides a Location header pointing at Memento that most closely matches the requested datetime. This allows the client to request this Memento in step [5]. With the Vary header, the server indicates it understood the client's datetime negotiation request. With the TCN header, the server indicates it chose a Memento, i.e. the one pointed at by the Location header. The TimeGate server also provides the following pointers in the Link header:
|
| [4] Case 6 |
TimeGate server detects Accept-Datetime & URI-G exists & datetime can be parsed & datetime is inside range for which server has Mementos for original resource URI-R & multiple Mementos exist for the requested datetime. Using the 300 status code, the server indicates that multiple resources meet the datetime preference that the client expressed in the Accept-Datetime header. This can occur if multiple Mementos exist for a given second, as the datetime format used in HTTP does not allow expressing granularities finer than a second. With the Vary header, the server indicates it understood the client's datetime negotiation request. With the TCN header, the server indicates it responds with a list of possible Mementos. This list of Mementos is provided in the Link header but could in addition be provided in a user-friendly way as HTML. The Link header points at the Original Resource (mandatory "original" relationship), at the TimeBundle (recommended "timebundle" relationship), and at the very first and most recent Mementos the server hosts for Original Resource URI-R (mandatory "first-memento", "last-memento" relationships). In addition, the server lists the mutliple resources that meet the client's datetime preference using the "memento" relationship type. This information allows a client to pick a Memento, and proceed to step [5]. 
|
| [4] Case 7 |
TimeGate server detects Accept-Datetime & URI-G exists & datetime can be parsed & datetime is outside range for which server has Mementos for original resource URI-R. Using the 406 status code, the server indicates the datetime value was out of range of the Mementos it hosts. With the Vary header, the server indicates it understood the client's datetime negotiation request. With the TCN header, the server indicates it responds with a list of possible Mementos. This list of Mementos is provided in the Link header but could in addition be provided in a user-friendly way as HTML. The Link header points at the Original Resource (mandatory "original" relationship), at the TimeBundle (recommended "timebundle" relationship), and at the very first and most recent Mementos the server hosts for Original Resource URI-R (mandatory "first-memento", "last-memento" relationships). This information allows a client to:
|
| [4] Case 8 |
TimeGate server detects Accept-Datetime & URI-G exists & datetime cannot be parsed. Using the 400 status code, the server indicates the datetime value was illegible. With the Vary header, the server indicates it understood the client's datetime negotiation intention. With the TCN header, the server indicates it responds with a list of possible Mementos. This list of Mementos is provided in the Link header but could in addition be provided in a user-friendly way as HTML. The Link header points at the Original Resource (mandatory "original" relationship), at the TimeBundle (recommended "timebundle" relationship), and at the very first and most recent Mementos the server hosts for Original Resource URI-R (mandatory "first-memento", "last-memento" relationships). This information allows a client to:
|
| [4] Case 9 |
TimeGate server detects Accept-Datetime & URI-G does not exist. 
|
| [3] |
Client issues HTTP GET request without Accept-Datetime header against TimeGate URI-G for Original Resource URI-R.
|
||||
| [4] | TimeGate server that is the target of request [3] responds: | ||||
| [4] Case 10 |
URI-G exists.
The TimeGate server provides a Location header pointing at the most recent Memento for Original Resource URI-R. This allows the client to request this Memento in step [5]. With the TCN header, the server indicates it chose a Memento, i.e. the one pointed at by the Location header. With the Vary header, the server indicates the datetime negotiation capability. The Link header points at the Original Resource (mandatory "original" relationship), at the TimeBundle (recommended "timebundle" relationship), and at the very first and most recent Mementos the server hosts for Original Resource URI-R (mandatory "first-memento", "last-memento" relationships). It also points at the Memento previous to the most recent one (optional "prev-memento" relationship), but for obvious reasons ommits a Link with relationship type "next-memento". Note how the Memento pointed at by the Location header is the same as the one pointed at by the Link header with relationship type "last-memento". 
|
||||
| [4] |
Case 11 URI-G does not exist.
|
|
|
|
| [5] |
Client issues HTTP GET request with Accept-Datetime header against Memento URI-M
for Original Resource URI-R:
|
| [6] | Memento server that is the target of request [5] responds: |
| [6] Case 12 |
URI-M exists.
The Memento server provides the requested Memento URI-M. The Memento server conveys the archival datetime of the Memento in the Content-Datetime header. The Memento server also provides the following pointers in the Link header:
|
| [6] Case 13 |
URI-M does not exist.
|
| [5] |
Client issues HTTP GET request without Accept-Datetime header against Memento URI-M
for Original Resource URI-R:
|
| [6] | The responses from the Memento server that is the target of this request are exaclty the same as listed above under [6], Cases 12 and 13. Servers that serve Mementos should always express the Content-Datetime of those Mementos, and always provide the Link header pointing at the Original Resource, other Mementos, and the TimeBundle. This information should be provided unconditionally. |