Revision System

All data elements (Node, Link, and Network) not only support storing arbitrary metadata, but are also versioned. Updates made to these elements are tracked through time. This tracking includes deletion. When any element is deleted, all prior versions are still available, but the element may not be modified further.

Specific snapshots of each element are referred to as revisions of those elements.

API Examples

Element creation

In creating an element, such as the Node below, the revision is always returned.

Request

CreateNode(properties={
  "_schema": "LossSet_1.0",
  "cedant": "Company Y",
  "region": "Eastern US",
  "internal_reference": "ABC123",
})

Response

{
  "id": 1,
  "revision": 10
}

Element update

When updating any element, the revision returned is always larger than the current revision. There is no guarantee that the new revision will be sequential.

Request

UpdateNode(properties={
    "_schema": "LossSet_1.0",
    "cedant": "Company Z",
    "region": "Western US",
    "internal_reference": "XYZ321",
  },
  reference={
    "id": 1
  }
)

Response

{
  "id": 1,
  "revision": 22
}

Update specific revision

A specific revision may be referenced for any operation (such as Update), but the overall outcome is identical.

Request

UpdateNode(properties={
    "_schema": "LossSet_1.0",
    "region": "Southern US",
    "internal_reference": "XYZ321",
  },
  reference={
    "id": 1,
    "revision": 10
  }
)

Response

{
  "id": 1,
  "revision": 24
}

Retrieval

Elements may be retrieved using their ID and revision, and the revision specified determines which version of that element is returned.

Request

ReadNode(with_inlined_properties=true,
  reference={
    "id": 1,
    "revision": 22
  }
)

Response

{
  "id": 1,
  "revision": 22,
  "properties": {
      "_schema": "LossSet_1.0",
      "cedant": "Company Z",
      "region": "Western US",
      "internal_reference": "XYZ321",
  }
}

Another version of the same element can be retrieved.

Request

ReadNode(with_inlined_properties=true,
  reference={
    "id": 1,
    "revision": 24
  }
)

Response

{
  "id": 1,
  "revision": 24,
  "properties": {
      "_schema": "LossSet_1.0",
      "region": "Southern US",
      "internal_reference": "XYZ321",
  }
}

The existing properties are not merged on update, as shown by the above example. Update is analogous to a PUT operation in REST.

Latest revision

When the revision is not provided, or is specified as 0, the most recent revision is assumed.

Request

ReadNode(with_inlined_properties=true,
  reference={
    "id": 1,
    "revision": 0
  }
)

Response

{
  "id": 1,
  "revision": 24,
  "properties": {
      "_schema": "LossSet_1.0",
      "region": "Southern US",
      "internal_reference": "XYZ321",
  }
}