Protocol Revision Metadata

Revisions figure at the protocol level in two ways

  • metadata retrieval variants

  • request revision specification

Revision Metadata Retrieval via HTTP

Revision metadata is available both through content negotiation on a repository's SPARQL service URI and in response to an HTTP request either to a repository resource specific to its timemap.

The SPARQL service URI for a given repository is

https://dydra.com/<account name>/<repository-name>/sparql

for which, a request with the single accept header application/link-format generates a Memento timemap as the response. For example

GET /jhacker/foaf
Host: dydra.com
Accept: application/link-format

returns the timemap for the jhacker/foaf repository encoded in the link format as introduced by Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, August 2012.

Revision Designator Specification

Dydra accepts the URL query parameter revision-id in SPARQL and Graph Store protocol requests to indicate that the request is to apply to a specific repository revision. For example,

GET /account/repository/sparql? \
  revision-id=a7b7ff5d-a73d-1545-be41-275337a28d70& \
  query=SELECT%20(%20count(*)%20as%20%3FstatementCount%20)%0A%20%20WHERE%20%7B%20%3Fs%20%3Fp%20%3Fo%20%7D \
  HTTP/1.1
Host: dydra.com

A specific revision is permitted for read-only queries only. Update operations apply to the current revision only.

A Revision reference takes one of several forms, which are described below.

Revision Window Specification

Dydra HTTP, MQTT, and WebSockets requests may include a window specification in the the request header Windows (or RevisionWindows) or the URL query argument windows (or revision-windows) to indicate the temporal properties of the target dataset to be used to determine the structure of streamed results. The header value takes the form of a WindowRef of the following syntax

WindowRef ::= ( 'R' Integer ? '/' ) ? WindowRelation
WindowRelation ::=  RevisionInterval ( '/' ( RevisionRef | XPathDuration ) ( '/' ( XPathDuration | Integer ) )? )?
RevisionInterval ::= RevisionRef | (RevisionRef '--' RevisionRef)
RevisionRef ::= UUID('~'('+'|'-')?[0-9]+)? | HEAD('~'('+'|'-')?[0-9]+)? | XPathDateTime | Integer

The windows can be either retrospective or prospective. Where a revision interval is specified, the specification is retrospective. Where HEAD is provided as the revision reference, the specification is prospective. This means that the query is applied to revisions as they are created by modifications made to the repository.