Revision System
===============

.. index:: Data Management API; 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
------------

.. contents::
  :depth: 1
  :local:


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",
      }
    }