This document will give you an overview about the HIRO Graph Developer WS API.
\nPlease be familiar with the HIRO Graph and the Websocket Protocol.
\nAll Requirements of HIRO Graph apply.
\n| \n\n | \n\nIn order to use the API you need to register an application, please drop us a line at support@hiro.almato.ai.\n | \n
All initial connect requests must contain a valid access token _TOKEN. Request a valid access token from the HIRO IAM server.
\nAll requests will be made against a base $url (e.g. core.almato.ai).
All further examples assume wss:// as the protocol.
The Streaming endpoint is located at /api/events-ws/.
The standard steps to follow are:
\nConnect
\nSubscribe to scope (if allscopes set to false)
\nRegister a filter
\nReceive data
\nconst ws = new WebSocket(`wss://${url}/api/events-ws/6/?groupId=&offset=`, ['events-1.0.0', 'token-' + token]);| Name | \nDescription | \nDefault | \n
|---|---|---|
groupId | \nsubscribe to the same event stream by opening multiple connections with the same groupId. The stream will be partitioned amongst all connections. If connection is lost, the groupId will allow you to receive any missed events. | \n'' | \n
offset | \n
| \n'' | \n
delta | \nOnly receive the changes to a vertex, not the whole vertex. Each a attribute in the event body is prefixed with | \nfalse | \n
allscopes | \nBy default, events from all scopes are subscribed to. Setting this to false, requires use of the | \ntrue | \n
const msg = {\n 'type': 'token',\n 'args': {\n _TOKEN: 'new token'\n }\n};\nws.send(JSON.stringify(msg));const msg = {\n 'type': 'subscribe',\n 'id': scope_id // The ogit/_id of the ogit/DataScope (i.e. the scope of your instance) you want to subscribe to\n};\nws.send(JSON.stringify(msg));const msg = {\n 'type': 'register',\n 'args': {\n 'filter-id': 'unique filter id for this websocket',\n 'filter-type': 'jfilter',\n 'filter-content': '(element.ogit/_type = ogit/Question)'\n }\n};\nws.send(JSON.stringify(msg));const msg = {\n 'type': 'unregister',\n 'args': {\n 'filter-id': 'unique filter id for this websocket'\n }\n};\nws.send(JSON.stringify(msg));const msg = {\n 'type': 'clear',\n 'args': {}\n};\nws.send(JSON.stringify(msg));Events contain the originator of the event, the action taken, and the contents.
\nBy default, the eventstream sends the entire body of the affected vertex.
\n{\n id: string; // ogit/_id from body\n body: {\n /* properties like ogit/_id */\n \"ogit/name\": \"My name\"\n },\n metadata: {\n \"ogit/_modified-by\": string;\n \"ogit/_modified-by-app\": string;\n \"ogit/_modified-on\": number;\n };\n nanotime: number;\n timestamp: number;\n type: \"CREATE\" | \"REPLACE\" | \"UPDATE\" | \"CONNECT\" | \"DISCONNECT\" | \"DELETE\" | \"WRITE_TIMESERIES\";\n}Delta events only contain the changes on the node. Each attribute is prefixed by +, -, =.
{\n id: string; // ogit/_id from body\n body: {\n /* properties like ogit/_id prefixed by change */\n \"+ogit/firstName\": \"My name\" // Added\n \"-ogit/lastName\": \"My name\" // Removed\n \"=ogit/email\": \"My name\" // Changed\n },\n metadata: {\n \"ogit/_modified-by\": string;\n \"ogit/_modified-by-app\": string;\n \"ogit/_modified-on\": number;\n };\n nanotime: number;\n timestamp: number;\n type: \"CREATE\" | \"REPLACE\" | \"UPDATE\" | \"CONNECT\" | \"DISCONNECT\" | \"DELETE\" | \"WRITE_TIMESERIES\";\n}In order to only receive certain events, filters can be registered. The filterType is currently only jfilter.
| Operator | \nDescription | \nSupported types | \nFilter example | \n
|---|---|---|---|
| \nequals to | \nString,\nNumber | \n
| \n
| \ndiffers from | \nString,\nNumber | \n
| \n
| \nmore than | \nNumber | \n
| \n
| \nmore or equals | \nNumber | \n
| \n
| \nless than | \nNumber | \n
| \n
| \nless or equals | \nNumber | \n
| \n
| \nnot | \nFilter | \n
| \n
| \nand | \nFilters | \n
| \n
| \nor | \nFilters | \n
| \n
wildcards | \nmatches all | \nString | \n
| \n
{\n 'filter-content': '&(element.ogit/_type=ogit/Question)(action=C*)'\n}The WS Graph API permits to do REST primitives over WS.\nThe WS Graph API endpoint is located at /api/graph-ws/.
| \n\n | \n\nBlobs can be fetched via this api, but they can only be stored via REST.\n | \n
const ws = new WebSocket(`wss://${url}/api/graph-ws/6/`, ['graph-2.0.0', 'token-' + token]);\nws.addEventListener(\"open\", function() {\n if (ws.protocol !== \"graph-2.0.0\") {\n throw new Error(\"Expecting WebSocket protocol 'graph-2.0.0', got \" + ws.protocol);\n }\n //do something with connection\n});Websocket API requests are JSON, and have the following structure:
\nconst request =\n{\n 'id': 'mandatory id for matching the reply',\n 'type': 'the type of the request, e.g. get, create, replace, connect, ...',\n '_TOKEN': 'optional, if none specified, the one from the establishing the websocket will be used',\n 'headers':\n {\n // headers for the request\n },\n 'body':\n {\n // body for the request\n }\n};ws.send(JSON.stringify(request));In order to do correct multiplexing in the websocket stream, all responses will be wrapped by an envelope.\nA client must buffer all messages until the flag more is false in an envelope.
Response Envelope:
\n{\n \"id\": \"id of the request\",\n \"more\": true|false // `false` if this is the last message for the response\n \"multi\": true|false // `true` if this response is fragmented, the stream of messages represents an array as the final result\n \"body\": []|{}|... // for responses with `multi=true` the body should be put to an array [] and when `more=false` the result should be the array with the assembled parts\n}In order to process these envelope which arrive intermixed with other response envelopes, one\nmust buffer the envelopes unti the last flag is true.
\nconst requests = {}; // holds all responses\n\nws.onmessage = function(msg)\n{\n const payload = JSON.parse(what);\n\n const request = requests[payload.id];\n if (!request) throw new Error(\"request could not be found \" + req.id);\n\n if (payload.error)\n {\n // an error must always be delivered\n request.cb(payload);\n delete(requests[payload.id]);\n } else if (!payload.multi && payload.more) {\n throw new Error(\"non-multi messages cannot be fragmented\");\n } else if (!payload.multi) {\n // thats a single response message\n request.cb(payload);\n delete(requests[payload.id]);\n } else {\n // thats a fragmented response, buffer up everything until payload.more = false\n if (payload.body !== null) request.buf.push(payload.body);request.buf.push(payload.body);\n\n if (!payload.more)\n {\n request.cb(request.buf);\n delete(requests[payload.id]);\n }\n };\n);{\n \"id\": \"request id\",\n \"type\": \"get\",\n /* other optional properties */\n \"headers\":\n {\n \"ogit/_id\": \"id of the node\"\n },\n \"body\":\n {\n // all parameters for the corresponding REST request are available here\n }\n}{\n \"id\": \"request id\",\n \"type\": \"create\",\n /* other optional properties */\n \"headers\":\n {\n \"ogit/_type\": \"type of the node\"\n },\n \"body\":\n {\n // all parameters for the corresponding REST request are available here\n }\n}{\n \"id\": \"request id\",\n \"type\": \"update\",\n /* other optional properties */\n \"headers\":\n {\n \"ogit/_id\": \"id of the node\"\n },\n \"body\":\n {\n // all parameters for the corresponding REST request are available here\n }\n}{\n \"id\": \"request id\",\n \"type\": \"replace\",\n /* other optional properties */\n \"headers\":\n {\n \"ogit/_id\": \"id of the node\",\n },\n \"body\":\n {\n // all parameters for the corresponding REST request are available here\n }\n}{\n \"id\": \"request id\",\n \"type\": \"delete\",\n /* other optional properties */\n \"headers\":\n {\n \"ogit/_id\": \"id of the node/edge\"\n },\n \"body\":\n {\n // all parameters for the corresponding REST request are available here\n }\n}{\n \"id\": \"request id\",\n \"type\": \"connect\",\n /* other optional properties */\n \"headers\":\n {\n \"ogit/_type\": \"type of the verb\"\n },\n \"body\":\n {\n \"out\": \"id of the outgoing node\",\n \"in\": \"id of the ingoing node\"\n }\n}{\n \"id\": \"request id\",\n \"type\": \"query\",\n /* other optional properties */\n \"headers\":\n {\n \"type\": \"type of the query, e.g. vertices\"\n },\n \"body\":\n {\n // all parameters for the corresponding REST request are available here\n }\n}{\n \"id\": \"request id\",\n \"type\": \"writets\",\n /* other optional properties */\n \"headers\":\n {\n \"ogit/_id\": \"id of the node\"\n },\n \"body\":\n {\n // all parameters for the corresponding REST request are available here\n }\n}{\n \"id\": \"request id\",\n \"type\": \"streamts\",\n /* other optional properties */\n \"headers\":\n {\n \"ogit/_id\": \"id of the node\"\n },\n \"body\":\n {\n // all parameters for the corresponding REST request are available here\n }\n}{\n \"id\": \"request id\",\n \"type\": \"history\",\n /* other optional properties */\n \"headers\":\n {\n \"ogit/_id\": \"id of the node\"\n },\n \"body\":\n {\n // all parameters for the corresponding REST request are available here\n }\n}{\n \"id\": \"request id\",\n \"type\": \"me\",\n '_TOKEN': 'optional, if none specified, the one from the establishing the websocket will be used',\n \"headers\":\n {\n },\n \"body\":\n {\n // all parameters for the corresponding REST request are available here\n }\n}{\n \"id\": \"request id\",\n \"type\": \"getcontent\",\n '_TOKEN': 'optional, if none specified, the one from the establishing the websocket will be used',\n \"headers\":\n {\n \"ogit/_id\": \"id of the node\"\n },\n \"body\":\n {\n // all parameters for the corresponding REST request are available here\n }\n}| \n\n | \n\nIn order to store blob content, the REST API must be used.\n | \n
The responses for receiving blob content are chunked envelopes looking like this, and the client needs to assemble these:
\n{\n \"id\": \"request id\",\n \"multi\": true,\n \"last\": true|false\n \"body\":\n {\n \"data\": \"chunk of blob data\",\n \"encoding\": \"base64\" // base64 is currently the only encoding possible\n }\n}All error codes of HIRO Graph API apply.
\nAll error codes of Websocket Protocol apply.
\n| \n\n | \n\nOn Websocket close message HIRO Graph error codes are not propagated and only Websocket Protocol codes are returned. If exists error from close message content should be used to recognize and implement handling. Example error response message:\n | \n
{\n \"error\": {\"message\": \"authentication required\"}\n}