Time Travel APIs

Last updated: April 23, 2015


Abstract

 This document describes the APIs that are associated with the Time Travel service.

Table of Contents

1. URI that redirects to a Memento
2. URI that provides access to a JSON description of a Memento
3. TimeMap for access to version history, as per the Memento protocol
    3.1. "Do It Yourself" TimeMap - Fast Response, the Client does the Heavy Lifting
    3.2. "We Do It" TimeMap - Slow Response, the Time Travel service does the Heavy Lifting
4. TimeGate for datetime negotiation, as per the Memento protocol
5. Time Travel Prediction Service - List of DIY TimeMap and TimeGate URIs of a Memento
6. Time Travel Archive Registry

1. URI that redirects to a Memento

 The Time Travel service provides an easy way to be redirected to a Memento for a given resource with an archival/version datetime that is close to a desired one.

Request

Simply append the desired datetime and the URI of the resource to the baseURL of this redirection service.

http://timetravel.mementoweb.org/memento/YYYY<MM|DD|HH|MM|SS>/URI

Request Example

Using https://github.com/mementoweb/SiteStory as an example URI, these are valid requests:

http://timetravel.mementoweb.org/memento/2013/https://github.com/mementoweb/SiteStory
http://timetravel.mementoweb.org/memento/201301/https://github.com/mementoweb/SiteStory
http://timetravel.mementoweb.org/memento/20130115/https://github.com/mementoweb/SiteStory
http://timetravel.mementoweb.org/memento/2013011510/https://github.com/mementoweb/SiteStory
http://timetravel.mementoweb.org/memento/201301151020/https://github.com/mementoweb/SiteStory
http://timetravel.mementoweb.org/memento/20130115102033/https://github.com/mementoweb/SiteStory

Response

A redirect (HTTP "302 Found" status code) to the Memento for the requested resource that is temporally closest to the desired datetime, irrespective of the memento_compliant archive or versioning system it resides in.

Response Example

HTTP/1.1 302 Found
Date: Fri, 31 Oct 2014 20:44:44 GMT
Content-Type: text/plain; charset=iso-8859-1
Content-Length: 0
Location: http://en.wikipedia.org/w/index.php?title=Web_archiving&oldid=526371727

Using the redirecting URI for linking in HTML

When using the redirecting URI in a link in HTML, please consider annotating the link with HTML5 extension attributes that make the link robust over time; see Robust Links for further information. Add the following attributes:
  • data-originalurl - The original URI of the resource for which the redirecting URI was created
  • data-versiondate - The datetime intended by the link, expressed as a ISO 8601 date using the Z notation.
These attributes make sure that this essential information about the link does not vanish and they can be used by memento_compliant tools, such as Memento for Chrome, to navigate towards the original URI or to other prior versions of it.

Example

Using the redirecting URI http://timetravel.mementoweb.org/memento/20130115102033/http://en.wikipedia.org/wiki/web_archiving as an example URI, this what the HTML link would look like: 
<a href="http://timetravel.mementoweb.org/memento/20130115102033/http://en.wikipedia.org/wiki/web_archiving" 
   data-originalurl="http://en.wikipedia.org/wiki/web_archiving"
   data-versiondate="2013-01-15T10:20:33Z">some text here</a>

2. URI that provides access to a JSON description of a Memento

 The Time Travel service provides access to a JSON document that details a Memento for a given resource with an archival/version datetime that is close to a desired one.

Request

Simply append the desired datetime and the URI of the resource to the baseURL of this JSON service.

http://timetravel.mementoweb.org/api/json/YYYY<MM|DD|HH|MM|SS>/URI

Request Example

Using http://cnn.com as an example URI, these are valid requests:

http://timetravel.mementoweb.org/api/json/2013/http://cnn.com
http://timetravel.mementoweb.org/api/json/201301/http://cnn.com
http://timetravel.mementoweb.org/api/json/20130115/http://cnn.com
http://timetravel.mementoweb.org/api/json/2013011510/http://cnn.com
http://timetravel.mementoweb.org/api/json/201301151020/http://cnn.com
http://timetravel.mementoweb.org/api/json/20130115102033/http://cnn.com

Response

A JSON document that lists the Memento for the requested resource that is temporally closest (closest) to the desired datetime, irrespective of the memento_compliant archive or versioning system it resides in. It also lists, when possible, the Mementos that are adjacent to the closest one (prev, next) as well as very first and most recent Mementos (first, last). For each Memento, it lists the archival/version datetime (datetime). For each of these Mementos, the response may list duplicates, i.e. Mementos with the same datetime but different URIs. In addition the document lists the URI for which the JSON was requested (original_uri), as well as the URI of the TimeGate (timegate_uri) and the TimeMap (timemap_uri) provided by the Time Travel service.

Response Example

Using the request http://timetravel.mementoweb.org/api/json/20130115102033/http://cnn.com as an example, this would be a sample JSON response that includes duplicates for the closest and most recent Mementos: 
{
  "original_uri": "http://www.cnn.com/",
  "mementos": {
    "last": {
      "datetime": "2014-10-07T18:32:00Z",
      "uri": [
        "http://web.archive.org/web/20141007183200/http://www.cnn.com/",
        "http://wayback.vefsafn.is/wayback/20141007183200/http://www.cnn.com/"
      ]
    },
    "next": {
      "datetime": "2013-01-15T11:01:01Z",
      "uri": [
        "http://web.archive.org/web/20130115110101/http://www.cnn.com/"
      ]
    },
    "closest": {
      "datetime": "2013-01-15T09:46:43Z",
      "uri": [
        "http://web.archive.org/web/20130115094643/http://www.cnn.com/",
        "http://archive.today/aaqIY"
      ]
    },
    "first": {
      "datetime": "2000-06-20T18:02:59Z",
      "uri": [
        "http://arquivo.pt/wayback/wayback/20000620180259/http://cnn.com/"
      ]
    },
    "prev": {
      "datetime": "2013-01-15T08:17:14Z",
      "uri": [
        "http://web.archive.org/web/20130115081714/http://www.cnn.com/"
      ]
    }
  },
  "timegate_uri": "http://timetravel.mementoweb.org/timegate/http://www.cnn.com/",
  "timemap_uri": {
    "link_format": "http://timetravel.mementoweb.org/timemap/link/http://cnn.com",
    "json_format": "http://timetravel.mementoweb.org/timemap/json/http://cnn.com"
  }
}

3. TimeMap for access to version history
The Time Travel service provides ways to access a TimeMap for a resource with a given URI. A TimeMap, as defined in the Memento protocol (RFC 7089), provides an overview of all Mementos (and their archival/version datetimes) known to the responding server. A brief description of TimeMaps is available in the Introduction to Memento.

As the Time Travel service covers many web archives and versioning systems, a TimeMap for any given resource can list Mementos available in multiple remote servers. Information about access to TimeMaps for individual systems is available in the Memento Depot. This document details access to TimeMaps that the Time Travel service aggregates across web archives and content management systems.

The Time Travel service provides access to two types of TimeMaps:
  • DIY TimeMap: Responses to requests for this type of TimeMap should be fast but the client is in charge of collecting further information based on the response.
  • WDI TimeMap: Responses to requests for this type of TimeMap can be fast in case they can be delivered from cache, but slow if this is not the case. All information is collected by the Time Travel service.
Each type of TimeMap is available in two serialization formats:
  • Serialized using the application/link-format MIME type that is required by the Memento protocol. The format is described in Section 5 of RFC 7089.
  • Serialized using the application/json MIME type. The format is described in JSON TimeMaps.

3.1. "Do It Yourself" TimeMap for access to version history
The DIY TimeMap service does not provide information about actual Mementos. Rather, it returns a list of TimeMap URIs that may be exposed by archives. The response is based on a machine learning approach that tries to determine which archives hold Mementos for which URIs. As such, some listed TimeMap URIs may actually not really exist and TimeMap URIs may exist that are not listed. The machine learning approach leans towards avoiding the latter. Responses should be fast but the client is left with the task of collecting information about actual Mementos across archives by dereferencing the listed TimeMap URIs.

The response, in both serialization formats, is delivered as an Index TimeMap. Index TimeMaps for the application/link-format serialization are described in Section 5.1.1 of RFC 7089. Index TimeMaps for the application/json serialization are described in JSON TimeMaps. In both serialization formats, information is provided that may be helpful to a client to decide whether or not to dereference a potential TimeMap URI:
  • An indicator as to whether the archive associated with the potential TimeMap URI is compliant with the Memento protocol or not.
  • A short name for the archive associated with the potential TimeMap URI. Values are provided by the Time Travel Archive Registry, in the id attribute of the link element.

Request

Simply append the format indicator (link or json) and the URI of the resource to the baseURL of the DIY TimeMap service.

http://timetravel.mementoweb.org/timemap/format/URI

Request Example

Using http://www.lamonitor.com as an example URI, the DIY TimeMap formatted according to the application/link-format MIME type is requested as follows:

http://timetravel.mementoweb.org/timemap/link/http://www.lamonitor.com

whereas the TimeMap formatted according to the application/json MIME type is requested as follows:

http://timetravel.mementoweb.org/timemap/json/http://www.lamonitor.com

Response

An Index TimeMap formatted according to the requested MIME type (application/link-format or application/json) that lists potential TimeMap URIs in various archives as well as some additional information about each of these archives. The Index TimeMap also lists the URI for which it provides an overview of potential TimeMap URIs, as well as the URI of the TimeGate and the TimeMap itself.

Response Example

Using the request http://timetravel.mementoweb.org/timemap/link/http://www.lamonitor.com as an example, this would be a DIY TimeMap response. Note that the title attribute is (ab)used to provide additional information about archives: 
<http://www.lamonitor.com>;rel="original",
<http://timetravel.mementoweb.org/timemap/link/http://www.lamonitor.com>
  ; rel="self" ; type="application/link-format",
<http://timetravel.mementoweb.org/timegate/http://www.lamonitor.com>
  ; rel="timegate",
<http://timetravel.mementoweb.org/can/timemap/link/http://www.lamonitor.com>
  ; rel="timemap" ; type="application/link-format" ; title="memento_compliant:no|archive_id:gcwa",
<http://timetravel.mementoweb.org/si/timemap/link/http://www.lamonitor.com>
  ; rel="timemap" ; type="application/link-format" ; title="memento_compliant:no|archive_id:si",
<http://web.archive.org/web/timemap/link/http://www.lamonitor.com>
  ; rel="timemap" ; type="application/link-format" ; title="memento_compliant:yes|archive_id:ia",
<http://archive.today/timemap/http://www.lamonitor.com>
  ; rel="timemap" ; type="application/link-format" ; title="memento_compliant:yes|archive_id:archive.is"
...
 
Using the request http://timetravel.mementoweb.org/timemap/json/http://cnn.com/ as an example, this would be a TimeMap Index response. Note the use of special-purpose parameters to convey additional information about archives: 
{
  "original_uri": "http://www.lamonitor.com",
  "timegate_uri": "http://timetravel.mementoweb.org/timegate/http://www.lamonitor.com",
  "timemap_index": [
    {
      "uri": "http://timetravel.mementoweb.org/can/timemap/link/http://www.lamonitor.com",
      "memento_compliant": "no",
      "archive_id": "gcwa"
    },
    {
      "uri": "http://timetravel.mementoweb.org/si/timemap/link/http://www.lamonitor.com",
      "memento_compliant": "no",
      "archive_id": "si"
    },
    {
      "uri": "http://archive.today/timemap/http://www.lamonitor.com",
      "memento_compliant": "yes",
      "archive_id": "archive.is"
    },
    {
      "uri": "http://web.archive.org/web/timemap/link/http://www.lamonitor.com",
      "memento_compliant": "yes",
      "archive_id": "ia"
    }
  ],
  "timemap_uri": {
    "json_format": "http://timetravel.mementoweb.org/timemap/json/http://www.lamonitor.com",
    "link_format": "http://timetravel.mementoweb.org/timemap/link/http://www.lamonitor.com"
  }
}

3.2. "We Do It" TimeMap for access to version history
For the WDI TimeMap service, all information about Mementos in various archives is collected by the Time Travel service. If this information is readily available from cache, responses should be fast. If it is not, the information will be collected on the fly and, hence, a response may take a while. For both serialization formats, the nature of the TimeMap that will be provided depends on the amount of Mementos that are known to the Time Travel service:
  • Up until a maximum of 1000 Mementos, the TimeMap will list all known Mementos.
  • When more than 1000 Mementos are known, an Index TimeMap will be provided. Index TimeMaps don't list Mementos but rather point at multiple TimeMaps that do. Index TimeMaps for the application/link-format serialization are described in Section 5.1.1 of RFC 7089. Index TimeMaps for the application/json serialization are described in JSON TimeMaps.

Request

Simply append the format indicator (link or json) and the URI of the resource to the baseURL of the WDI TimeMap service.

http://labs.mementoweb.org/timemap/format/URI

Request Example

Using http://www.w3.org/TR/webarch/ as an example URI, the WDI TimeMap formatted according to the application/link-format MIME type is requested as follows:

http://labs.mementoweb.org/timemap/link/http://www.w3.org/TR/webarch/

Using http://cnn.com as an example URI, the WDI TimeMap formatted according to the application/json MIME type is requested as follows:

http://labs.mementoweb.org/timemap/json/http://cnn.com/

Response

A TimeMap formatted according to the requested MIME type (application/link-format or application/json) that lists all Mementos for the requested resource known by the Time Travel service. The TimeMap also lists the URI for which it provides an overview of known Mementos, as well as the URI of the TimeGate and the TimeMap itself.

Response Example

Using the request http://labs.mementoweb.org/timemap/link/http://www.w3.org/TR/webarch/ as an example, this would be (an excerpt of) a TimeMap response: 
<http://www.w3.org/TR/webarch/>; rel="original",
<http://labs.mementoweb.org/timemap/link/http://www.w3.org/TR/webarch/>
  ; rel="self"; type="application/link-format"
  ; from="Wed, 11 Sep 2002 07:39:33 GMT"
  ; until="Fri, 10 Oct 2014 13:25:07 GMT",
<http://timetravel.mementoweb.org/timegate/http://www.w3.org/TR/webarch/>; rel="timegate",
<http://web.archive.org/web/20020911073933/http://www.w3.org/TR/webarch/>
  ; rel="first memento"; datetime="Wed, 11 Sep 2002 07:39:33 GMT",
<http://web.archive.org/web/20021010101032/http://www.w3.org/TR/webarch/>
  ; rel="memento"; datetime="Thu, 10 Oct 2002 10:10:32 GMT",
<http://web.archive.org/web/20021203004021/http://www.w3.org/TR/webarch/>
  ; rel="memento"; datetime="Tue, 03 Dec 2002 00:40:21 GMT",
....
 
Using the request http://labs.mementoweb.org/timemap/json/http://cnn.com/ as an example, this would be a TimeMap Index response: 
{
  "original_uri": "http://cnn.com/",
  "timegate_uri": "http://timetravel.mementoweb.org/timegate/http://cnn.com/",
  "timemap_uri": {
    "json_format": "http://labs.mementoweb.org/timemap/json/http://cnn.com/",
    "link_format": "http://labs.mementoweb.org/timemap/link/http://cnn.com/"
  },
  "timemap_index": [
    {
      "from": "2000-06-21T04:41:56Z",
      "until": "2005-05-12T22:25:15Z",
      "uri": "http://labs.mementoweb.org/timemap/1/json/http://cnn.com/"
    },
    {
      "from": "2005-05-13T00:00:13Z",
      "until": "2010-10-05T20:30:51Z",
      "uri": "http://labs.mementoweb.org/timemap/2/json/http://cnn.com/"
    },
    {
      "from": "2010-10-06T00:00:57Z",
      "until": "2014-12-20T12:22:34Z",
      "uri": "http://labs.mementoweb.org/timemap/3/json/http://cnn.com/"
    }
  ]
}

4. TimeGate for datetime negotiation

 The Time Travel service exposes a TimeGate for a resource with a given URI. A TimeGate, as defined in the Memento protocol (RFC 7089), supports datetime negotiation, a variant of content negotiation. Datetime negotiation allows direct access to an archived snapshot or a version of the resource as it existed at some desired datetime in the past. A brief description of TimeGates is available in the Introduction to Memento.

When negotiating with a TimeGate, the desired datetime is provided in the Accept-Datetime HTTP request header. The TimeGate exposed by the Time Travel service will look for the Memento that is temporally closest to the desired datetime; it will include several web archives and content management systems in that lookup. Information about TimeGates for individual systems is available in the Memento Depot. This document details datetime negotiation with the aggregate TimeGate exposed by the Time Travel service.

Request

The request is an HTTP HEAD/GET against the TimeGate http://timetravel.mementoweb.org/timegate/URI, whereby URI is the URI of the resource for which a Memento is sought. The request includes an Accept-Datetime request header that provides the desired datetime expressed in GMT using the HTTP date format.

Request Example

Using http://www.ietf.org/ as an example URI, the cURL command to request a Memento with an archival/version datetime close to June 16 2012 is: 
curl -I \
-H "Accept-Datetime: Sat, 16 Jun 2012 00:00:00 GMT" \
http://timetravel.mementoweb.org/timegate/http://www.ietf.org/

Response

The response has an HTTP "302 Found" status code and the URI of the selected Memento is provided in the Location header. It can be recognized to be the response of a TimeGate because of the Accept-Datetime value of the Vary header. The response also includes a Link header with links to the resource for which the TimeGate was accessed, to a TimeMap, to the selected Memento, as well as to the very first and most recent Memento if known to the Time Travel service.

Response Example

This is the response to the aforementioned cURL request: 
HTTP/1.1 302 Found
Date: Fri, 31 Oct 2014 20:44:44 GMT
Content-Type: text/plain; charset=iso-8859-1
Content-Length: 0
Location: http://web.archive.org/web/20120616161314/http://www.ietf.org/
Vary: Accept-Datetime
Link: <http://www.ietf.org/> ;rel="original" ,
 <http://timetravel.mementoweb.org/timemap/link/1/http://www.ietf.org/> 
    ; rel="timemap"
    ; type="application/link-format",
 <http://web.archive.org/web/20120616161314/http://www.ietf.org/> 
    ; rel="memento"
    ; datetime="Sat, 16 Jun 2012 16:13:14 GMT",
 <http://web.archive.org/web/19961106114954/http://www.ietf.org/> 
    ; rel="memento first"
    ; datetime="Wed, 06 Nov 1996 11:49:54 GMT",
 <http://web.archive.org/web/20140901131113/https://www.ietf.org/> 
    ; rel="memento last"
    ; datetime="Mon, 01 Sep 2014 13:11:13 GMT"

5. Time Travel Prediction Service - List of DIY TimeMap and TimeGate URIs of a Memento

 The Time Travel prediction service returns a list of TimeMap and TimeGate URIs of a Memento that may be exposed by archives. The response is based on a machine learning approach that tries to determine which archives hold Mementos for which URIs. This approach is similar to the approach explained in the DIY TimeMap service. The response does not provide information about actual Mementos and the client is left with the task of collecting this information by dereferencing the listed URIs. The machine learning prediction could also list URIs in archives that may not exist or could not list URIs from archives that may contain the Memento. The Time Travel approach is tuned to avoid the later scenario.

The response is delivered in JSON serialization with information that may be useful to a client to decide whether or not to dereference a potential URI:
  • An indicator as to whether the archive associated with the potential TimeMap URI is compliant with the Memento protocol or not.
  • A short name for the archive associated with the potential TimeMap URI. Values are provided by the Time Travel Archive Registry, in the id attribute of the link element.

Request

Simply append the desired URI of the resource to the baseURL of this JSON service.

http://timetravel.mementoweb.org/prediction/json/URI

Request Example

Using http://cnn.com as an example URI, the JSON response is requested as:

http://timetravel.mementoweb.org/prediction/json/http://cnn.com

Response

A JSON document that lists potential TimeMap and TimeGate URIs in various archives as well as some additional information about each of these archives. The document also lists the URI for which it provides an overview of potential URIs.

Response Example

Using the request http://timetravel.mementoweb.org/prediction/json/http://cnn.com as an example, this would be a sample JSON response: 
{
  "original_uri": "http://cnn.com",
  "memento_info": [
    {
      "timegate_uri": "http://web.archive.org/web/http://cnn.com",
      "timemap_uri": "http://web.archive.org/web/timemap/link/http://cnn.com",
      "memento_compliant": "yes",
      "archive_id": "ia"
    },
    {
      "timegate_uri": "http://web.archive.bibalex.org/web/http://cnn.com",
      "timemap_uri": "http://web.archive.bibalex.org/web/timemap/link/http://cnn.com",
      "memento_compliant": "yes",
      "archive_id": "ba"
    },
    {
      "timegate_uri": "http://www.webarchive.org.uk/wayback/archive/http://cnn.com",
      "timemap_uri": "http://www.webarchive.org.uk/wayback/archive/timemap/link/http://cnn.com",
      "memento_compliant": "yes",
      "archive_id": "blarchive"
    },
    {
      "timegate_uri": "http://timetravel.mementoweb.org/can/timegate/http://cnn.com",
      "timemap_uri": "http://timetravel.mementoweb.org/can/timemap/link/http://cnn.com",
      "memento_compliant": "no",
      "archive_id": "gcwa"
    },
    {
      "timegate_uri": "http://timetravel.mementoweb.org/aueb/timegate/http://cnn.com",
      "timemap_uri": "http://timetravel.mementoweb.org/aueb/timemap/link/http://cnn.com",
      "memento_compliant": "no",
      "archive_id": "aueb"
    },
    {
      "timegate_uri": "http://timetravel.mementoweb.org/si/timegate/http://cnn.com",
      "timemap_uri": "http://timetravel.mementoweb.org/si/timemap/link/http://cnn.com",
      "memento_compliant": "no",
      "archive_id": "si"
    }
  ]
}

6. Time Travel Archive Registry

 The Time Travel service covers a range of web archives and version control systems both compliant and not compliant with the Memento protocol. The covered systems are listed in the Time Travel Archive Registry. This list is provided as an XML file with a yet undocumented format. Still, many of the used parameter names should be self-explanatory for Memento developers.

In addition to the listed systems, the Time Travel service covers those that provide an explicit pointer to preferred TimeGates and/or TimeMaps, such as MediaWikis that have installed one of the Memento extensions for MediaWiki or systems that have implemented and personalized the generic TimeGate server software.