Skip to main content
Version: 2.0

GraphGrid Curator

Platform Version 2.0

API Version 1.0

Intro to Curator​

GraphGrid Curator is responsible for the flow control of graph data. Flow control is an important tool utilized in data communications in order to manage the transmission of data amongst nodes. While overseeing the presentation of data, Curator integrates with other GraphGrid services such as Search and Publish to provide a fully integrated experience capable of handling a spectrum of simple to demanding projects. Curator includes a dashboard management interface which builds on top of several core modules that perform core graph visualization rendering and interoperability. Curator is powered by the Curator API.

Environment​

Curator requires the following integrations:

  • ONgDB 1.0+

Create example project​

A project must be created before a user can begin using Curator. A project contains the positions and information belonging to the user nodes on the project workspace; as well as the graph's pan (x, y) and zoom (k) values. Once a project is created, its projectId will be used for all future edits. A project can also have multiple versions. When a project is created, a project node with single version node attached to it is created in the database, as well as a versionId. In this example, we are going to name this particular project "Test Project". See Create Project (and Version) to view the example request and response object.

Save project​

If a node is desired to be translated into the graph, or if the graph itself needs to be zoomed or panned, then this new information needs to be saved to the graph in order for it to be recalled properly. After any operation, all nodes that have been translated and the graphs zoom (k) and pan (x, y) coordinates need to be saved to the version. These are only specific to the version and have no effect on other users' projects. Save Project.

Get project version data​

After any operation that modifies the graph, such as editing an edge, node, translating a node, hiding a node, deleting a node, or adding a node, the Get Project Version Graph Data endpoint needs to be hit in order to get the newest data for a project. In the future, this will be refactored into those operation responses instead of having a separate call.

Copy​

If you would like to create an exact copy of your version into another project, use the Copy Project endpoint.

Share​

If you would like to share this version of your project with another user and give that user permission to make edits, use the Share Project endpoint. You can share the version with any user(s) in your organization for collaboration. Keep in mind that all edits will appear under your version and all users will see all users' edits.

Delete Project​

A project may be soft-deleted by using the Delete Project endpoint. This operation can be reversed. The project will still appear in the Get Projects response, however, but with a deleted: true property. Additionally, the project will still be available to view via the Get Project Version Graph Data endpoint. It is up to the frontend application to filter the deleted projects, or conversely this endpoint can be used to show which projects have been deleted. An un-delete route is planned.

Add nodes and edges​

Create single node​

Once we have a project (and version) id, we're able to add a node. The create node endpoint accepts an object with a single node label and another object of all its properties. The properties may only be strings or numbers. The node's id will be returned inside the response body, which will be used for all subsequent operations on this particular node. Let's create a Movie node for "Star Wars: The Empire Strikes Back." Using the same version id we just created, we are going to submit the title along with any other information we want about this movie to the API (Create Node and Add to Project).

Add Node Property​

Using the returned node id, we can add a new property to the Star Wars Movie. Let's add a weather property to our newly created node. Using the update node property endpoint, (Update/Add Node Property) we can update or add properties on a particular node.

Add Existing Node to Project​

We will add an existing node for the movie "Blade Runner." Now we can add connections to this node. Follow the example at Add Existing Node to Project. The endpoint accepts node x and y coordinates if you have a specific place on the graph you would like the newly created node to appear. Otherwise, the location may be determined at a later point.

Expand Neighbors​

Now that we have two nodes on the graph, "Blade Runner" and "Star Wars: The Empire Strikes Back." We can expand any node and add its neighboring nodes (distance n=1) to a version. Let's expand "Blade Runner" by sending in its node id, as detailed at Add Node Neighbors to Version. The response body will include the ids of all neighboring nodes that were added to the version. If you request the project with the current version using Get Project Version Graph Data, you will notice that all nodes neighbors exist in the version.

Delete Nodes​

Depending on the kind of data we want, we can always delete a node that we created. Please reference the Delete Node section. The deleted node, and any attached edges, will be deleted for all projects. A successful request will return an empty array. You can verify that the node property has been deleted by calling Get Project Version Graph Data.

caution

This call runs a DETACH DELETE, meaning the node(s) and all their relationships are deleted. A node with relationships cannot be deleted without removing the relationships. This operation cannot be reversed.

Hide Node from Project​

If the graph appears too cluttered, you can hide a node (along with any edges attached to it). Using the node id, we can hide it from our version view. A hidden node will also have any attached edges hidden as well. Hidden nodes and edges will still return inside the response of Get Project Version Graph Data -- it must be filtered out by the frontend application.

note

This node (and its edges) will remain intact on all other users' versions and CAN be undone by adding a node to the version.

Create a node reference (file upload)​

A file, (reference), may be attached to a node. Create Node Reference will create the file in the s3 bucket/folder specified, create a reference node, then attach that reference node to that particular node.

Get node references​

After a reference is created for a node, the actual reference data must be obtained by querying the node itself (it is NOT returned inside the graph data to keep the payload small). Please reference Get Node References.

Create Edge between two nodes​

Nodes can have multiple edges between them in order to visualize node connections. After using Expand Neighbors to expand the "Blade Runner" movie node, we noticed that Harrison Ford is an actor in it. We also know that Harrison Ford is in "Star Wars: The Empire Strikes Back." With this information, we can create an edge between the two nodes. An edge between two nodes has a direction which is specified by the source and target node ids. An edge also has a single type and can contain string or number properties. We will send in the ids of the movie node and the person node, and any information about the edge to create it. Notice that there's no version id. This is because this connection will be available for all users. Please reference the Create Edge section for more information.

Edit Edge Property​

After creating the edge between Harrison Ford and "Star Wars: The Empire Strikes Back", we researched the film more and found out that Harrison Ford received around 4 million usd for the movie. We would like to add this to the edge. Reference Update Edge Property for more on how to create or update an edge property.

Modify Edge Type​

You may also change an edge's type. An edge can only have one type at a time. See Modify Edge Type.

Delete Edge​

This is how to delete an edge. This edge will be deleted for all projects. Please reference the Delete Edge section for more.

caution

This operation cannot be reversed.

Curator API​

Projects​

Create Project (and Version)​

Creates a project.

  • Base URL: /1.0/viz/project
  • Method: POST
Example Request​
curl --location --request POST "${API_BASE}/1.0/viz/project" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
"projectTitle":"Test Project",
"projectStatement":"test statement"
}'
Response (200)​
{
    "user": {
        "lastLogin": 1608672141421,
        "lastName": "Master",
        "lastModifiedBy": "anonymousUser",
        "version": 1,
        "displayEmail": "webmaster@graphgrid.com",
        "firstName": "Graph",
        "phoneNumber": "",
        "displayUsername": "graphgrid",
        "createdBy": "anonymousUser",
        "name": "Graph Master",
        "enver": 0,
        "email": "webmaster@graphgrid.com",
        "username": "graphgrid",
        "id": "grn:gg:user:vI89KFxzPJjC3D9GqngETdyHJdR9c23G0mzMwrBTSm76"
    },
    "project": {
        "created": 1608672141480,
        "id": "grn:gg:project:bU43KGxzpOuB1DOKdshWQydVDgQ7f91F0wkBpqNFZy88"
    },
    "version": {
        "id": "grn:gg:version:bU43KGxzpOuB1DOKdshWQydVDgQ7f91F0wkBpqNFZy88",
        "properties": {
            "lastUpdated": 1608672141480,
            "created": 1608672141480,
            "projectNumber": "",
            "x": 0,
            "y": 0,
            "k": 1,
            "projectTitle": "Test Project",
            "projectStatement": "test statement",
            "id": "grn:gg:version:bU43KGxzpOuB1DOKdshWQydVDgQ7f91F0wkBpqNFZy88"
        }
    }
}

Save Project​

Saves skew, zoom, and node positions of current graph to version.

  • Base URL: /1.0/viz/version/{{versionId}}/save
  • Method: POST
Example Request​
curl --location --request POST "${API_BASE}/1.0/viz/version/grn:gg:version:bU43KGxzpOuB1DOKdshWQydVDgQ7f91F0wkBpqNFZy88/save" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw {
    "nodePositions": [{
        "id": "grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0",
        "x": 167,
        "y": 500
    }],
    "transformState": {
        "k": 1,
        "x": 204,
        "y": 75
    }
}
Response (200)​
{
    "lastUpdated": 1609876241469,
    "updatedBy": "graphgrid",
    "created": 1608672141480,
    "projectNumber": "",
    "x": 204,
    "y": 75,
    "k": 1,
    "projectStatement": "test statement",
    "projectTitle": "Test Project",
    "id": "grn:gg:version:bU43KGxzpOuB1DOKdshWQydVDgQ7f91F0wkBpqNFZy88"
}

Get Projects​

Gets existing projects.

  • Base URL: /1.0/viz/projects
  • Method: GET
Example Request​
curl --location --request GET "${API_BASE}/1.0/viz/projects" \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Response (200)​
[
    {
        "id": "grn:gg:project:bU43KGxzpOuB1DOKdshWQydVDgQ7f91F0wkBpqNFZy88",
        "created": 1608672141480,
        "versions": [
            {
                "headerElementInchPoundGrn": null,
                "packagingGrn": null,
                "assessmentImplName": null,
                "wordDocAnchorGrn": null,
                "scopeScopeElementGrn": null,
                "notesGrn": null,
                "lastUpdated": 1608672141480,
                "projectTitle": "Test Project 970002470591155",
                "additionalPackagingStatementsElementGrn": null,
                "applicableDocumentsGrn": null,
                "verificationsGrn": null,
                "assessmentImplGrn": null,
                "notesFirstArticleElementGrn": null,
                "notesIntendedUseElementGrn": null,
                "id": "grn:gg:version:bU43KGxzpOuB1DOKdshWQydVDgQ7f91F0wkBpqNFZy88",
                "requirementsGrn": null,
                "scopeGrn": null,
                "projectNumber": "",
                "headerElementDateGrn": null,
                "sharedUsers": [],
                "headerElementSpecificationGrn": null,
                "owner": {
                    "firstName": "Graph",
                    "lastName": "Master",
                    "email": "webmaster@graphgrid.com",
                    "id": "grn:gg:user:vI89KFxzPJjC3D9GqngETdyHJdR9c23G0mzMwrBTSm76"
                },
                "firstPageHeaderGrn": null,
                "packagingElementGrn": null,
                "projectStatement": "test statement",
                "notesStandardSamplesElementGrn": null,
                "documentReferencesGrn": null,
                "deleted": null,
                "created": 1608672141480
            }
        ]
    }
]

Get Project Version Graph Data​

Returns graph data for a graph project version. Includes skew, nodes, and edges.

  • Base URL: /1.0/viz/data/all/{{versionId}}
  • Method: GET
Example Request​
curl --location --request GET "${API_BASE}/1.0/viz/data/all/grn:gg:version:bU43KGxzpOuB1DOKdshWQydVDgQ7f91F0wkBpqNFZy88" \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Response (200)​
{
    "links": [],
    "nodes": [
        {
            "x": 0,
            "y": 0,
            "hidden": null,
            "id": "grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0",
            "properties": {
                "title": "Star Wars: The Empire Strikes Back",
                "id": "grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0"
            },
            "labels": ["GraphGridResource", "Movie"],
            "connections": 0
        }
    ],
    "graphTransform": {
        "x": 0,
        "y": 0,
        "k": 1
    }
}

Delete Project​

Soft deletes a project (adds a bool delete property). Deletes project and all versions attached to it.

  • Base URL: /1.0/viz/version/{{versionId}}
  • Method: DELETE
Example Request​
curl --location --request DELETE "${API_BASE}/1.0/viz/delete/version/grn:gg:version:bU43KGxzpOuB1DOKdshWQydVDgQ7f91F0wkBpqNFZy88" \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Response (200)​
{
    "lastUpdated": 1609792102434,
    "deleted": true,
    "created": 1609792102434,
    "projectNumber": "",
    "x": 0,
    "y": 0,
    "k": 1,
    "projectStatement": "test statement",
    "projectTitle": "Test Project 8831746135926051",
    "id": "grn:gg:version:bU43KGxzpOuB1DOKdshWQydVDgQ7f91F0wkBpqNFZy88"
}

Copy Project​

Copies project to a new project (Save As).

  • Base URL: /1.0/viz/version/{{versionId}}/project
  • Method: POST
Example Request​
curl --location --request POST "${API_BASE}/1.0/viz/version/grn:gg:version:bU43KGxzpOuB1DOKdshWQydVDgQ7f91F0wkBpqNFZy88/project" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
"projectTitle":"Test Project Clone"
}'
Response (200)​
{
    "id": "grn:gg:version:B9OqrQulYIfE2o7Pyqrl5hSRHn5Ua1lICjrenHuqRgOq",
    "projectTitle": "Test Project Clone"
}

Share Project​

Shares project with other users of the organization. Shared users will have permission to edit and will be editing same graph.

  • Base URL: /1.0/viz/version/{{versionId}}/share
  • Method: POST
Example Request​
curl --location --request POST "${API_BASE}/1.0/viz/version:B9OqrQulYIfE2o7Pyqrl5hSRHn5Ua1lICjrenHuqRgOq/share" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "sharedUserIds":[
        "grn:gg:user:vI89KFxzPJjC3D9GqngETdyHJdR9c23G0mzMwrBTSm76"
    ]
}'
Response (200)​
{
    "results": {
        "version": {
            "lastUpdated": 1528332738072,
            "updatedBy": "anonymousUser",
            "created": 1528331860815,
            "x": 150.9635741298075,
            "y": 54.128998624684186,
            "k": 0.8490962464468399,
            "id": "grn:gg:version:B9OqrQulYIfE2o7Pyqrl5hSRHn5Ua1lICjrenHuqRgOq",
            "projectTitle": "Test Project Clone"
        },
        "shared_with": {
            "created": {
                "low": -675460307,
                "high": 355
            }
        },
        "user": {
            "lastName": "Master",
            "firstName": "Graph",
            "id": "grn:gg:user:vI89KFxzPJjC3D9GqngETdyHJdR9c23G0mzMwrBTSm76",
            "username": "graphgrid"
        }
    }
}

Users​

Get Users​

Gets all user nodes under Curator management.

  • Base URL: /1.0/viz/users
  • Method: POST
Request​
curl --location --request GET "${API_BASE}/1.0/viz/users" \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Response (200)​
{
    "nodes": [
        {
            "id": 21,
            "labels": ["User", "Resource"],
            "properties": {
                "lastLogin": 1610133891882,
                "lastName": "Master",
                "grn": "grn:gg:user:vI89KFxzPJjC3D9GqngETdyHJdR9c23G0mzMwrBTSm76",
                "lastModifiedBy": "anonymousUser",
                "version": 1,
                "displayEmail": "webmaster@graphgrid.com",
                "firstName": "Graph",
                "phoneNumber": "",
                "displayUsername": "graphgrid",
                "createdBy": "anonymousUser",
                "name": "Graph Master",
                "enver": 0,
                "email": "webmaster@graphgrid.com",
                "username": "graphgrid"
            }
        }
    ]
}

Get AllUsers​

This endpoint searches for all users under the same organization.

  • Base URL: /1.0/viz/allusers
  • Method: POST
Request​
curl --location --request GET "${API_BASE}/1.0/viz/allusers" \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Response (200)​
{
    "users": [
        {
            "lastLogin": 1610133795395,
            "lastName": "Master",
            "lastModifiedBy": "anonymousUser",
            "version": 1,
            "displayEmail": "webmaster@graphgrid.com",
            "firstName": "Graph",
            "phoneNumber": "",
            "displayUsername": "graphgrid",
            "createdBy": "anonymousUser",
            "name": "Graph Master",
            "enver": 0,
            "email": "webmaster@graphgrid.com",
            "username": "graphgrid",
            "id": "grn:gg:user:vI89KFxzPJjC3D9GqngETdyHJdR9c23G0mzMwrBTSm76"
        }
    ]
}

Nodes​

Create Node and Add to Project​

Creates a new node and attaches it to the current project. Must specify a single label and as many properties as needed in body.

  • Base URL: /1.0/viz/node/{{versionId}}
  • Method: POST
Request​
curl --location --request POST "${API_BASE}/1.0/viz/node/grn:gg:version:bU43KGxzpOuB1DOKdshWQydVDgQ7f91F0wkBpqNFZy88" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "label": "Movie",
    "properties": {
        "title": "Star Wars: The Empire Strikes Back"
    }
}'
Response (200)​

This response presents broken behavior with plans to be addressed in the future. Though the response returns a null array, the node is added successfully. The nodeId can be retrieved via the Get Project Version Graph Data endpoint.

[null]

Add Existing Node to Project​

Adds an existing node to a project.

  • Base URL: /1.0/viz/project/node
  • Method: POST
Request​
curl --location --request POST "${API_BASE}/1.0/viz/project/node" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "versionId": "grn:gg:version:JwTU9VR2ATT95BlPYCjauQm6pIR1ZO9IdojbtQJbwbY9",
    "nodeId": "grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0",
    "coordinates": [
        677,
        205.5
    ]
}'
Response (200)​
{
    "lastUpdated": 1610379267184,
    "created": 1610379267184,
    "projectNumber": "",
    "x": 0,
    "y": 0,
    "k": 1,
    "projectStatement": "test statement",
    "projectTitle": "Test Project",
    "id": "grn:gg:version:JwTU9VR2ATT95BlPYCjauQm6pIR1ZO9IdojbtQJbwbY9"
}

Add Node Neighbors to Version​

Expands all neighbors attached to a node and adds them to project.

  • Base URL: /1.0/viz/neighbors/{{nodeId}}
  • Method: POST
ParameterDescription
nodeLabel stringLabel of the node to expand
nodeId stringId of node to expand.
Request​
curl --location --request POST "${API_BASE}/1.0/viz/neighbors/grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "versionId": "grn:gg:version:JwTU9VR2ATT95BlPYCjauQm6pIR1ZO9IdojbtQJbwbY9"
}'
Response (200)​
[
    "grn:gg:version:rL1yEoOODJZhT1ShQYzWVknnRNJEZIuNAi28n9r1O0ti",
    "grn:gg:test:hSaWvPMZeJeFM4C5yBTBYyCCAWpFG7mZV6l1l8lgpDdp"
]

Update/Add Node Property​

Updates or creates a node property.

  • Base URL: /1.0viz/node/{{nodeId}}/{{property}}
  • Method: POST
ParameterDescription
nodeLabel stringLabel of node.
nodeId stringString value representing the id of a node.
property stringThe node's user-defined property key.
Request​
curl --location --request POST "${API_BASE}/1.0/viz/node/grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0/weather" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "value": "cold"
}'
Response (200)​
{
    "id": "grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0",
    "properties": {
        "weather": "cold",
        "title": "Star Wars: The Empire Strikes Back"
    },
    "labels": ["GraphGridResource", "Movie"]
}

Delete Node Property​

Deletes a property from a node.

info

A successful response will return an empty array. You can verify that the node property was deleted by calling Get Project Version Graph Data.

  • Base URL: /1.0/viz/node/{{nodeId}}/{{property}}
  • Method: DELETE
ParameterDescription
nodeLabel stringLabel of node.
nodeId stringString value representing the id of a node.
property stringName of property to delete.
Request​
curl --location --request DELETE "${API_BASE}/1.0/viz/node/grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0/weather"\
--header "Authorization: Bearer ${BEARER_TOKEN}"
Response (200)​
[]

Add Node Label​

Adds a label to a node.

  • Base URL:/1.0/viz/node/label/{{nodeId}}/{{label}}
  • Method: POST
ParameterDescription
nodeLabel stringLabel of node.
nodeId stringString value representing the id of a node.
label stringUser-defined name of label to create.
Request​
curl --location --request POST "${API_BASE}/1.0/viz/node/label/grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0/SciFi" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '[{
    "newLabels": [
        "Movie",
        "Resource",
        "SciFi"
    ]
}]'
Response (200)​
[
    {
        "newLabels": ["GraphGridResource", "Movie", "SciFi"]
    }
]

Delete Node Label​

Deletes a label from a node

  • Base URL:/1.0/viz/node/label/{{nodeId}}/{{label}}
  • Method: DELETE
ParameterDescription
nodeLabel stringLabel of node.
nodeId stringString value representing the id of a node.
label stringUser-defined name of label to delete.
Request​
/curl --location --request DELETE "${API_BASE}/1.0/viz/node/label/grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0/SciFi" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '[{
    "newLabels": [
        "Movie",
        "Resource"
    ]
}]'
Response (200)​
[
    {
        "newLabels": ["Movie", "Resource"]
    }
]

Hide Node​

Hides nodes from current project only. May be added to project again.

  • Base URL:/1.0/viz/hide/node
  • Method: POST
Request​
curl --location --request POST "${API_BASE}/1.0/viz/hide/node" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
    "versionId":"grn:gg:version:JwTU9VR2ATT95BlPYCjauQm6pIR1ZO9IdojbtQJbwbY9"",
    "nodeIds":["grn:gg:test:hSaWvPMZeJeFM4C5yBTBYyCCAWpFG7mZV6l1l8lgpDdp"]
}'
Response (200)​
{
    "id": "grn:gg:test:hSaWvPMZeJeFM4C5yBTBYyCCAWpFG7mZV6l1l8lgpDdp"
}

Delete Nodes​

Deletes a node from all projects.

  • Base URL: /1.0/viz/delete/node/
  • Method: POST
Request​
curl --location --request POST "${API_BASE}/1.0/viz/delete/node" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{"nodeIds": ["grn:gg:person:64xfOYrC5Nwh87Gn8LwOMr88B0WlAnzkGXYNBcctMzun"]}'
Response (200)​
[]

References (File Upload)​

Create Node Reference​

Uploads a file and attaches it to a node as a reference.

  • Base URL: /1.0viz/file/upload
  • Method: POST
curl "${API_BASE}/1.0/viz/file/upload" \
  -H 'Connection: keep-alive' \
  -H "authorization: Bearer ${BEARER_TOKEN}" \
  -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 11_1_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.88 Safari/537.36' \
  -H 'Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryVnRUObCWfuMeMoSq' \
  -H 'Accept: */*' \
  -H 'Origin: http://gg.graphgrid.com' \
  -H 'Referer: http://gg.graphgrid.com/workspace' \
  -H 'Accept-Language: en-US,en;q=0.9' \
  -H 'Cookie: _ga=GA1.2.1819078606.1606838082' \
  --data-binary $'------WebKitFormBoundaryVnRUObCWfuMeMoSq\r\nContent-Disposition: form-data; name="filename"\r\n\r\ntest\r\n------WebKitFormBoundaryVnRUObCWfuMeMoSq\r\nContent-Disposition: form-data; name="fileData"; filename="Screen Shot 2021-01-11 at 13.18.48.png"\r\nContent-Type: image/png\r\n\r\n\r\n------WebKitFormBoundaryVnRUObCWfuMeMoSq--\r\n' \
  --compressed \
  --insecure
Response (200)​
[]

Get Node References​

Returns a list of all node references

  • Base URL: /1.0/viz/references/{{nodeId}}
  • Method: GET
Request​
Response (200)​
[
    {
        "description": "test",
        "id": "grn:gg:reference:36cd2d82-e93c-4x23-931e-df120c498fa0",
        "fileURL": "https/url",
        "title": "test",
        "fileType": "image/png",
        "fileId": "grn:gg:file:bJbl73Zo43LiBFx8IhhMjtzq2qCIOAhs4kcHYKVYtG5R"
    }
]

All Graph Nodes and Properties​

Returns all labels and node properties for an organization. Warning: Not suitable for graphs above 10k nodes/relationships; ensure sufficient memory available.

  • Base URL: /1.0/viz/labels
  • Method: GET
Request​
curl --location --request GET "${API_BASE}/1.0/viz/labels" \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Response (200)​
[
    {
        "properties": {
            "title": "Star Wars: The Empire Strikes Back",
            "id": "grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0"
        },
        "id": "grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0",
        "labels": ["Movie"]
    },
    {
        "properties": {
            "weather": "cold",
            "title": "Star Wars: The Empire Strikes Back",
            "id": "grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0"
        },
        "id": "grn:gg:movie:iedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0",
        "labels": ["Movie"]
    },
    {
        "properties": {
            "id": "grn:gg:test:hSaWvPMZeJeFM4C5yBTBYyCCAWpFG7mZV6l1l8lgpDdp"
        },
        "id": "grn:gg:test:hSaWvPMZeJeFM4C5yBTBYyCCAWpFG7mZV6l1l8lgpDdp",
        "labels": ["SciFi", "test"]
    },
    {
        "properties": {
            "name": "Harrison Ford",
            "id": "grn:gg:person:DF85L4hnG3mqruSl6ysk8S5cIau43lotFo8mTDAjHZX8"
        },
        "id": "grn:gg:person:DF85L4hnG3mqruSl6ysk8S5cIau43lotFo8mTDAjHZX8",
        "labels": ["Person"]
    }
]

Edges​

Create Edge​

Creates a new edge in bank. Must specify a label, target and source node id, and as many edge properties as needed.

  • Base URL: /1.0/viz/edge
  • Method: POST
ParameterDescription
versionId stringId of current project's version
type string,integerThe edge type.
properties stringThe properties associated with the edge.
sourceNodeIdId of the node that determines the starting direction of the edge.
targetNodeIdId of the node that determines where the direction of the edge points to.
Request​
curl --location --request POST "${API_BASE}/1.0/viz/edge" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{"type":"ACTED_IN","properties":{},
    "sourceNodeId": "grn:gg:movie:giedqFkIWpad1Oa90BahVotfUTOVuPECAqWTjJ9gWTUk0",
    "targetNodeId": "grn:gg:person:DF85L4hnG3mqruSl6ysk8S5cIau43lotFo8mTDAjHZX8"
}'
Response (200)​
{
    "id": "grn:gg:acted_in:puNzDHxkkRw3W1ka7HP0VOhKg6bUMwuR8wGceutqMOwe",
    "properties": {
        "createdBy": "graphgrid",
        "id": "grn:gg:acted_in:puNzDHxkkRw3W1ka7HP0VOhKg6bUMwuR8wGceutqMOwe"
    },
    "type": "ACTED_IN"
}

Update Edge Property​

Updates or creates an edge property.

  • Base URL: /1.0/viz/edge/{{edgeId}}/{{property}}
  • Method: POST
ParameterDescription
versionId stringId of current project's version
type string,integerThe edge type.
properties stringThe properties associated with the edge.
sourceNodeIdId of the node that determines the starting direction of the edge.
targetNodeIdId of the node that determines where the direction of the edge points to.
Request​
curl --location --request POST "${API_BASE}/1.0/viz/edge/grn:gg:acted_in:puNzDHxkkRw3W1ka7HP0VOhKg6bUMwuR8wGceutqMOwe/profit" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
"value":"40 million usd"
}'
Response (200)​
[
    {
        "createdBy": "graphgrid",
        "profit": "40 million usd",
        "id": "grn:gg:connected:puNzDHxkkRw3W1ka7HP0VOhKg6bUMwuR8wGceutqMOwe"
    }
]

Modify Edge Type​

Updates an edge type.

Base URL: /1.0/viz/edge/{{edgeId}}/type Method: PUT

ParameterDescription
edgeId stringId of the edge to be modified.
Request​
curl --location --request PUT "${API_BASE}/1.0/viz/edge/grn:gg:{{edgeType}}:{{edgeId}}/type" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{
"type":"TV Series"
}'
Response (200)​
[
    {
        "id": "grn:gg:acted_in:799dcc6a-1d08-4d7b-8932-823629d9e01a",
        "type": "TV Series"
    }
]

Delete Edge Property​

Deletes an edge property.

  • Base URL: /1.0/viz/edge/{{edgeId}}/{{property}}
  • Method: DELETE
Request​
curl --location --request DELETE "${API_BASE}/1.0/viz/edge/grn:gg:connected:3hCZ4YlQguZgapKmMMf5AZD2JYOfVTjswP9T9pBhtPzz/profit" \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Response (200)​
[]

Delete Edges​

Deletes an edge from all projects.

  • Base URL: /1.0/viz/delete/edge/{{edgeId}}
  • Method: POST
Request​
curl --location --request POST "${API_BASE}/1.0/viz/delete/edge" \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-raw '{"edgeIds":["grn:gg:connected:3hCZ4YlQguZgapKmMMf5AZD2JYOfVTjswP9T9pBhtPzz"]}'
Response (200)​
[]

Health​

Application Health​

  • Base URL: /1.0/viz/status
  • Method: GET
Request​
curl --location --request GET "${API_BASE}/1.0/viz/status"
Response (200)​
{
    "timestamp": 1610398747116,
    "uptime": 18514.1392395,
    "application": {
        "name": "viz-network-server",
        "version": "1.0.0",
        "pid": 268,
        "title": "node",
        "argv": [
            "/usr/bin/node",
            "/app/dist/index.js"
        ],
        "versions": {
            "node": "14.8.0",
            "v8": "8.4.371.19-node.12",
            "uv": "1.38.1",
            "zlib": "1.2.11",
            "brotli": "1.0.7",
            "ares": "1.16.0",
            "modules": "83",
            "nghttp2": "1.41.0",
            "napi": "6",
            "llhttp": "2.0.4",
            "openssl": "1.1.1g",
            "cldr": "37.0",
            "icu": "67.1",
            "tz": "2020a",
            "unicode": "13.0"
        },
        "node_env": "prod"
    },
    "resources": {
        "memory": {
            ...
        },
        "loadavg": [
           ...
        ],
        "cpu": [
            {
               ...
                }
        ],
        "disk": [
            {
                ...
            }
        ],
        "nics": {
            "lo": [
                {
                   ...
                }
            ],
            "eth0": [
                {
                    ...
                }
            ]
        }
    },
    "system": {
        ...
    }
}

Prerequisites​

  • OAuth service
  • ONgDB bolt connection
  • All nodes must have a unique and immutable id.
  • All edges must have a unique and immutable id.
  • Any data that should appear in the graph should have the label specified in RESOURCE_LABEL.
  • All globals defined
  • Users returned from auth service must be found in database.

Environment Variables​

CLIENT_ORG
The GraphGrid Org name.

NODE_ENV
The GraphGrid Environment in which to run the application.

ONGDB_HOST
The full URI of the GraphGrid OngDB Cluster endpoint.

ONGDB_USER
The GraphGrid ONgDB Cluster username.

ONGDB_PW
The GraphGrid Cluster password.

USER_ALIAS
The GraphGrid ONgDB Label reserved for GraphGrid Users.

IDENTIFIER
A property name reserved for the unique identifier on nodes and edges e.g. 'grn'. Nodes that do not have this identifier may be filtered automatically from certain endpoints.

RESOURCE_LABEL
A GraphGrid ONgDB Label reserved for all nodes created by Curator and all nodes that are ingested that should appear in the graph. Nodes that do not have this Label may be filtered automatically from certain endpoints.

REFERENCE_BUCKET The bucket and folder(s) location in S3 where references will be stored.

SECURITY_USERNAME
The GraphGrid username used for OAuth authentication.

SECURITY_PASSWORD
The GraphGrid password used for OAuth authentication.

Example Configuration​

[
    {
        "name": "CLIENT_ORG",
        "value": "pizzahut"
    },
    {
        "name": "NODE_ENV",
        "value": "prod"
    },
    {
        "name": "ONGDB_HOST",
        "value": "xxxx.graphgrid.com"
    },
    {
        "name": "ONGDB_USER",
        "value": "ongdb"
    },
    {
        "name": "ONGDB_PW",
        "value": "xxxxxxxxx"
    },
    {
        "name": "USER_ALIAS",
        "value": "GraphGridUser"
    },
    {
        "name": "IDENTIFIER",
        "value": "grn"
    },
    {
        "name": "RESOURCE_LABEL",
        "value": "GraphGridResource"
    },
    {
        "name": "REFERENCE_BUCKET",
        "value": "prod/images"
    },
    {
        "name": "SECURITY_USERNAME",
        "value": "xxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    {
        "name": "SECURITY_PASSWORD",
        "value": "xxxxxxxxxxxxxxxxxxxxxxxxx"
    }
]
info

Fig 1: Path from organization user to resource node (Org)-[:ORGANIZATION_USER]->(User)-[:HAS_PROJECTGROUP]-> (ProjectGroup)-[:HAS_PROJECT]->(Project)-[:HAS_VERSION]->(Version{deleted: false})-[:HAS_NODE{x: 0, y: 0, hidden: false}]-> (RESOURCE_LABEL) (Version)-[:SHARED_WITH]->(User)

info

Fig: 2 Two Users with Versions that share a node
Nodes that appear in search or that are created by use (and subsequently available in search) must contain the specified RESOURCE_LABEL Nodes that are created by these applications services will have the appropriate resource label (do not specify it on create node); however, ingest and existing graph data does not automatically add this label. Without the label, they will not be available to add to a version.
All nodes with the RESOURCE_LABEL specified will be available for all users to add to their graph version. If two versions have the same node, they will both have pointers to that node (along with the position and visibility of the node in that particular version). There is no need to tag edges with a particular type for them to appear. If a version has two RESOURCE_LABEL nodes that have an edge between them, both versions will also have the same edge.