HIRO Graph List API

Migration Topics
Integration
Concepts
Best Practices
Api

Changelog
HIRO API Overview
HIRO Audit API
HIRO Graph - Gremlin Query
HIRO Graph Action API
HIRO Graph Auth API
HIRO Graph List API
HIRO Graph WebSocket API
Refresh Token

HIRO Graph List API

The list API allows one to maintain multiple values for one property. A property normally looks like:

{ "ogit/name": "HIRO" }

A listified property looks like

{"ogit/name": [{"value": "foo"}, {"value": "bar", "created": 1523360364631}]}

whereas the inner structure is actually stored as stringified JSON:

{"ogit/name": [{"value":"foo"}, {"value":"bar", "created":1523360364631}]}

In order to work with list values, the normal API calls can be used, with prefixed field names. In order to read listified values as list, parameter listMeta should be used.

Once a value is converted to list it stays as list, but it is still allows to manipulate the list values as a normal value. In that case a list is replaced with a new one element list (see examples).

EXAMPLE of reading:

GET https://{url}/{id}?listMeta=true

If created key was not set, it will be added automatically set to now in milliseconds.

Setting the contents of a list

By using = as the first key to a property name, one will set the values of the list removing all others.

BEFORE:

  {
    "ogit/name": "hello"
  }

UPDATE json:

  {
    "=ogit/name": [{"value": "foo"}, {"value": "bar"}]
  }

AFTER with listMeta:

  {
    "ogit/name": [{"value": "foo", "created": 1523360364631}, {"value": "bar", "created": 1523360364631}]
  }

AFTER without listMeta:

  {
    "ogit/name": "[\"foo\", \"bar\"]"
  }

Update in backwards-compatible mode

BEFORE:

  {
    "ogit/name": [{"value": "foo", "created": 1523360364000}]
  }

UPDATE json:

  {
    "ogit/name": "bar"
  }

AFTER with listMeta:

  {
    "ogit/name": [{"value": "bar", "created": 1523360364635}]
  }

AFTER without listMeta:

  {
    // one element list is represented as scalar element
    "ogit/name": "bar"
  }

Update, which doesn’t change meta of values:

BEFORE:

  {
    "ogit/name": [{"value": "foo", "created": 1523360364000}]
  }

UPDATE json:

  {
    // If 'created' field is not specified by update, and value exists in a list,
    // it will not get new `created` timestamp
    "=ogit/name": [{"value": "foo"}]
    // OR
    "ogit/name": "foo"
  }

AFTER with listMeta:

  {
    "ogit/name": [{"value": "foo", "created": 1523360364000}
  }

AFTER without listMeta:

  {
    // one element list is represented as scalar element
    "ogit/name": "foo"
  }

Adding to the contents of a list

By using + as the first key to a property name, one can add one or more values.

BEFORE:

  {
    "ogit/name": [{"value": "foo", "created": 1523360364631}, {"value": "bar", "created": 1523360364631}]
  }

UPDATE json:

  {
    "+ogit/name": [{"value": "foobar"}]
  }

AFTER with listMeta:

  {
    "ogit/name": [
        {"value": "foo", "created": 1523360364631},
        {"value": "bar", "created": 1523360364631},
        {"value": "foobar", "created": 1523360364633}
     ]
  }

AFTER without listMeta (order has no garanties):

  {
    "ogit/name": "[\"foobar\", \"foo\", \"bar\"]"
  }

Removing from the contents of a list

By using - as the first key to a property name, one can remove one or more values. Specifying properties in the removal call will only remove those items in the list, that match all properties specified by the item to remove.

BEFORE:

  {
    "ogit/name": [{"value": "foo", "created": 1523360364631}, {"value": "bar", "created": 1523360364631}]
  }

UPDATE json:

  {
    "-ogit/name": [{"value": "foo", "created": 1523360364631}, {"value": "bar", "created": 0}]
  }

AFTER with listMeta:

  {
    "ogit/name": [{"value": "bar", "created": 1523360364631}]
  }

Converting to list

One can create a list by calling any of = on a scalar property value:

BEFORE:

  {
    "ogit/name": "foo"
  }

UPDATE json:

  {
    "=ogit/name": [{"value": "foo", "created": 1523360364631}, {"value": "bar", "created": 1523360364631}]
  }

AFTER:

  {
    "ogit/name": [{"value": "foo", "created": 1523360364631}, {"value": "bar", "created": 1523360364631}]
  }

Removing existing scalar property with list API, if value has no created timestamp (not in a list form), vertex ogit/_created-on should be used instead:

BEFORE:

  {
    "ogit/name": "foo",
    "ogit/_created-on": "15233603640000"
  }

UPDATE json:

  {
    "-ogit/name": [{"value": "foo", "created": 15233603640000}]
  }

AFTER:

  {
  }