History Resource Naming

The ERMrest history resource names have a common root relative to an identified catalog:

  • service /catalog/ cid /history/ from , until

where the components in this URL structure are:

  • service: the ERMrest service endpoint such as https://www.example.com/ermrest.
  • cid: the catalog identifier for one dataset such as 42.
  • from: a lower bound snapshot identifier for a history range, such as as 2NJ-6ZXW-FDFE
  • until: an upper bound snapshot identifier for a history range, such as 2PY-1MC0-VMZ2

In some history resources, either or both of from and until MAY be the empty string in order to express a partially bound interval. However, for history amendment, the effective until boundary MUST be clamped by the implementation to only affect dead storage. In other words, history amendment operation cannot affect live catalog state.

History Range

The historical range of the catalog is named as:

  • service /catalog/ cid /history/,

This is the root history with neither upper or lower bound specified in the URL.

Historical ACLs

Historical ACL resources are named as:

  • service /catalog/ cid /history/ from , until /acl
  • service /catalog/ cid /history/ from , until /acl/ RID

The first form names the set of catalog ACLs, while the second form names a set of model-element ACLs for a specific subject identified by its static RID property. Subjects identified by RID may be:

  • One schema
  • One table
  • One column
  • One foreign key

Historical ACL Bindings

Historical ACL binding resources are named as:

  • service /catalog/ cid /history/ from , until /acl_binding/ RID

This URL names a set of model-element ACL bindings for a specific subject identified by its static RID property. Subjects identified by RID may be:

  • One table
  • One column
  • One foreign key

Historical Annotations

Historical annotation resources are named as:

  • service /catalog/ cid /history/ from , until /annotation
  • service /catalog/ cid /history/ from , until /annotation/ RID

The first form names the set of catalog annotations, while the second form names a set of model-element annotations for a specific subject identified by its static RID property. Subjects identified by RID may be:

  • One schema
  • One table
  • One column
  • One key
  • One foreign key

Historical Attributes

Historical attribute resources are named as:

  • service /catalog/ cid /history/ from , until /attribute/ cRID
  • service /catalog/ cid /history/ from , until /attribute/ cRID / fRID = val

These URLs name a set of attributes (values) bound to the column identified by cRID which is the static RID property of one column definition in the model. The first form names attributes for all entity snapshots within the historical interval. The second form is further restricted to only entities matching a simple value test where another filtering column identified by fRID is bound to the provided static value val.

The second, filtering, form of historical attribute URL supports several idioms:

  1. By using an fRID corresponding to the RID column and a val corresponding to one record ID, any column of a specific entity can be addressed.
  2. By using an fRID and cRID corresponding to the RID of a data column, all entities with the same val can be addressed.