It's all very well for me to assert that this API makes sure your data goes into the database in a predictable manner, but just what is that manner?

The database

Syscat uses Neo4j as its DBMS.

It's a property-graph database, with a well-documented query language.

For an introduction to Neo4j concepts, without any reference to Syscat, this page is a good starting point.

Resources

These are stored as nodes.

They're actually stored as parent/child sets of nodes, where the parent contains metadata such as the UID and the creation datestamp, and its children contain versions of its attribute-set.

Metadata nodes

Each metadata node is given one Neo4j label, which identifies its resourcetype. Relationships between resources are recorded in the database as relationships between these nodes.

It contains two properties:

• ScUID
  • The Syscat Unique IDentifier, after the API has ensured it's URL-safe.
• ScCreateddate
  • An integer in Unix epoch format, i.e. the number of seconds since midnight at the start of January 1, 1970.
    • This system is not subject to the 2038 bug, a.k.a. the Epochalypse, because Syscat doesn't treat it as a 32-bit integer. It'll just keep on incrementing.
  • This records the date and time at which the metadata node itself was created, separating this from when any of its versions were created.

You'll see Sc in many of the names here, as well as SC a reserved prefix in the API. It's an abbreviation of Syscat.

The values of user-defined attributes are stored in attribute nodes.

Attribute nodes

These have the label ScVersion.

Resource attributes are represented as properties on the node, in the Neo4j datatype that most closely corresponds to that specified for an attribute in the schema. The absence of a property is the equivalent of NULL in SQL: it means "this value is not known."

Two system-defined attributes are also recorded in each attribute node:

• ScVersion
  • This is an integer datestamp, in the same Unix epoch format that's used for ScCreateddate on the metadata nodes.
  • This serves two purposes:
    1. It records the date and time at which this version was created, providing an "updated at date/time" marker that's independent of when the resource itself was created.
    2. It uniquely identifies this version of the resource's attribute-values.
• ScVersioncomment
  • This is an optional (but recommended) string of text, for a summary description of what was changed in this version.

Attribute nodes are connected to their parent metadata nodes by an SC_HAS_VERSION relationship from the metadata node to each of its version nodes. There is no corresponding SC_VERSION_OF relationship that connects a version back to its metadata node, because the API never creates a link to these from anywhere else.

There is one additional relationship from the metadata node to exactly one of its version nodes: SC_CURRENT_VERSION links to the "current" version of the attributes. This relationship is updated when you create a new version of a resource's attributes, and when you use the API to change the current version.