This reference document will guide you through the API usage that helps working with Sense API.

Standard API Codes

Standard API error codes

Code Description
400 Bad input parameter. Error message should indicate which one and why.
401 Unauthorized or expired token.
403 Forbidden.
404 File or folder not found at the specified path.
405 Request method not supported.
500 Internal server error.

Sample error response :

{
  "status": "unsuccessful",
  "results": [
    {
      "error": "",
      "message": ""
    }
  ],
  "successful": false
}

Standard API success codes

Code Description
200 Success, A successful api execution is indicated with this code.

Data Management

Add node


URL Structure : /api/node

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
node Required Node to be added body Model

Sample request :

{
  "entityType": "Resort",
  "properties": [
    {
      "inequalityOperator": "EQUAL",
      "name": "Name",
      "value": "Disney's Contemporary Resort"
    },
    {
      "inequalityOperator": "EQUAL",
      "name": "Address",
      "value": "4600 North World Dr., Orlando, FL 32830, USA"
    }
  ]
}

Add nodes with associations


URL Structure : /api/node-pairs

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
nodePairs Required List of node pairs to be added to graph. body Model

Sample request :

[
  {
    "nodeFrom": {
      "entityType": "Resort",
      "properties": [
        {
          "inequalityOperator": "EQUAL",
          "name": "Name",
          "value": "Disney's Contemporary Resort"
        }
      ]
    },
    "nodeTo": {
      "entityType": "Facility",
      "properties": [
        {
          "inequalityOperator": "EQUAL",
          "name": "Name",
          "value": "Disney's Contemporary Resort Convention Center"
        }
      ]
    },
    "relationship": "contained_within",
    "relationshipProps": []
  }
]

Update node

Under this section you will be provided with functional methods to update a node. The property given by the uniqueKey is used to check if the node currently exist in the graph. If there exits a matching node, that node is updated. Otherwise a node is created.


URL Structure : /api/node

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
node Required Node with updated properties body Model
uniqueKey Required Unique key which is used to find node in graph query string
value Required Value for unique key query string

Sample request body :

{
  "entityType": "Resort",
  "properties": [
    {
      "inequalityOperator": "EQUAL",
      "name": "Name",
      "value": "Disney's Contemporary Resort"
    },
    {
      "inequalityOperator": "EQUAL",
      "name": "Address",
      "value": "4600 North World Dr., Orlando, FL 32830, USA"
    }
  ]
}

Delete node


URL Structure : /api/node

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
uniqueKey Required Unique key which is used to find node in graph query string
value Required Value for unique key query string

Delete all nodes

This method can be used to delete all nodes in the database, i.e. to reset the database


URL Structure : /api/nodes

Method : DELETE

Parameters : none

Import nodes via CSV

This method can be used to import nodes from csv files into graph


URL Structure : /api/nodes/csv

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
csv Required CSV url to import data query string
type Required Entity type of importing nodes query string

Import associations via CSV

This method can be used to import associations data from csv files into graph


URL Structure : /api/associations/csv

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
csv Required CSV url to import data query string
association Required Header of the csv which contains the type of association query string
association-from Required Header of the csv which contains the start node of association query string
association-to Required Header of the csv which contains the end node of association query string
id-key Required Id key query string

Search nodes

This returns a list of nodes that matches with the given criteria


URL Structure : /api/nodes

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
node Required Node to be matched body Model

Sample request :

{
  "entityType": "Resort",
  "properties": []
}

Search paths

Search the database and return paths(node-relation paths) that match with given paths


URL Structure : /api/paths

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
relatedNodePairs Required List of node pairs that specify the paths that should be searched body Model

Sample request :

[
  {
     "nodeFrom": {
      "entityType": "",
      "properties": [
        {
          "name": "MerchandiseFacilityType",
          "inequalityOperator": "EQUAL",
          "value": "Slide"
        }
      ]
    },
    "nodeTo": {
      "entityType": "Facility",
      "properties": [
        {
          "name": "MerchandiseFacilityType",
          "inequalityOperator": "EQUAL",
          "value": "Parks & More"
        }
      ]
    },
    "relationship": null,
    "isSingleNode": false,
    "relationshipProps": []
  }
]

Schema Management

Under this section you will be provided with functional methods to manage database schema. It is essential to create the database schema before inserting data.

Create graph

Create a graph by the given name


URL Structure : /api/schema/graphs

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
graph-name Required Graph name query string
authResponse Required Auth response body Model

Sample request :

{
  "accessToken": "string",
  "expiresIn": 0,
  "idToken": "string",
  "openIdProvider": "string",
  "refreshToken": "string"
}

Get all graphs

Get all graphs accessible to the user


URL Structure : /api/schema/graphs/info

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
authResponse Required Auth response body Model

Sample request :

{
  "accessToken": "string",
  "expiresIn": 0,
  "idToken": "string",
  "openIdProvider": "string",
  "refreshToken": "string"
}

Add node schema

Add the given node type and attributes to the schema


URL Structure : /api/schema/nodes

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
graph-key Required Graph key query string
access-token Required User's access token query string
nodeSchema Required Schema to be inserted body Model

Get node schema

Retrieves all node types and attributes in the schema


URL Structure : /api/schema/nodes

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
graph-key Required Graph key query string
access-token Required User's access token query string

Delete node schema

Delete the given node type from the schema. All data in the deleted data type are also deleted


URL Structure : /api/schema/nodes

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
graph-key Required Graph key query string
access-token Required User's access token query string
label Required Node type to be deleted path string

Add association schema

Add the given association type and attributes to the schema


URL Structure : /api/schema/associations

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
graph-key Required Graph key query string
access-token Required User's access token query string
associationSchema Required Schema to be inserted body Model

Sample request :

{
  "from": "string",
  "name": "string",
  "properties": [
    {
      "primary": true,
      "propertyName": "string",
      "propertyType": "STRING"
    }
  ],
  "to": "string"
}

Get association schema

Retrieves all association types and patterns in the schema


URL Structure : /api/schema/associations

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
graph-key Required Graph key query string
access-token Required User's access token query string

Delete association schema

Delete the given association type from the schema


URL Structure : /api/schema/associations

Method : DELETE

Parameters :

Parameters Value Description Parameter Type Data Type
graph-key Required Graph key query string
access-token Required User's access token query string
name Required Association type to be deleted path string

Global Knowledge

Add local-global schema mapping


URL Structure : /api/knowledge/mapping/schemas

Method : POST

Parameters :

Parameters Value Description Parameter Type Data Type
graph-key Required Graph key query string
access-token Required User's access token query string
mappings Required Schema mapping to be created body Modal

Sample body :

{
  "allowNodeMapping": true,
  "globalSchemaLabel": "string",
  "graphKey": "string",
  "localSchemaLabel": "string",
  "propertyMap": [
    {
      "globalLabel": "string",
      "localLabel": "string"
    }
  ]
}

Get local-global schema mapping


URL Structure : /api/knowledge/mapping/schemas

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
graph-key Required Graph key query string
access-token Required User's access token query string
local-schema-label Required User's schema label query string

Update local-global schema mapping

This will update internal knowledge on schema and will try to extract nodes and associations using the given user feedback and prior knowledge. Extracted nodes and associations are not added to the graph.


URL Structure : /api/knowledge/criteria

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
text Required Text to extract search criteria query string
suggestedFeatures Required User feedback for the extracted text body Model

Delete local-global schema mapping

This will update internal knowledge on schema and will try to extract nodes and associations using the given user feedback and prior knowledge. Extracted nodes and associations are not added to the graph.


URL Structure : /api/knowledge/criteria

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
text Required Text to extract search criteria query string
suggestedFeatures Required User feedback for the extracted text body Model

Set local-global node mapping

This will update internal knowledge on schema and will try to extract nodes and associations using the given user feedback and prior knowledge. Extracted nodes and associations are not added to the graph.


URL Structure : /api/knowledge/criteria

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
text Required Text to extract search criteria query string
suggestedFeatures Required User feedback for the extracted text body Model

Get global node mapped to local node

This will update internal knowledge on schema and will try to extract nodes and associations using the given user feedback and prior knowledge. Extracted nodes and associations are not added to the graph.


URL Structure : /api/knowledge/criteria

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
text Required Text to extract search criteria query string
suggestedFeatures Required User feedback for the extracted text body Model

Update local-global node mapping

This will update internal knowledge on schema and will try to extract nodes and associations using the given user feedback and prior knowledge. Extracted nodes and associations are not added to the graph.


URL Structure : /api/knowledge/criteria

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
text Required Text to extract search criteria query string
suggestedFeatures Required User feedback for the extracted text body Model

Delete local-global node mapping

This will update internal knowledge on schema and will try to extract nodes and associations using the given user feedback and prior knowledge. Extracted nodes and associations are not added to the graph.


URL Structure : /api/knowledge/criteria

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
text Required Text to extract search criteria query string
suggestedFeatures Required User feedback for the extracted text body Model

Set auto-mapping approval

This will update internal knowledge on schema and will try to extract nodes and associations using the given user feedback and prior knowledge. Extracted nodes and associations are not added to the graph.


URL Structure : /api/knowledge/criteria

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
text Required Text to extract search criteria query string
suggestedFeatures Required User feedback for the extracted text body Model

Get auto-mapping approval status

Extract searchable criteria with a query. Retrieved criteria with single node can be inserted to Search nodes . Other criteria with node pairs can be inserted to Search paths.


URL Structure : /api/knowledge/criteria

Method : GET

Parameters :

Parameters Value Description Parameter Type Data Type
text Required Text to extract search criteria query string

Sample request : find all facilities (for a graph containing nodes of type Facility)

Sample response :

{
  "results": [
    {
      "nodeFrom": {
        "entityType": "Facility",
        "properties": []
      },
      "nodeTo": {
        "entityType": "",
        "properties": []
      },
      "relationship": null,
      "isSingleNode": true,
      "relationshipProps": []
    }
  ]
}

Delete auto-mapping approval

This will update internal knowledge on schema and will try to extract nodes and associations using the given user feedback and prior knowledge. Extracted nodes and associations are not added to the graph.


URL Structure : /api/knowledge/criteria

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
text Required Text to extract search criteria query string
suggestedFeatures Required User feedback for the extracted text body Model

Search global knowledge

This will update internal knowledge on schema and will try to extract nodes and associations using the given user feedback and prior knowledge. Extracted nodes and associations are not added to the graph.


URL Structure : /api/knowledge/criteria

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
text Required Text to extract search criteria query string
suggestedFeatures Required User feedback for the extracted text body Model

Search neighbors of mapped global node

This will update internal knowledge on schema and will try to extract nodes and associations using the given user feedback and prior knowledge. Extracted nodes and associations are not added to the graph.


URL Structure : /api/knowledge/criteria

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
text Required Text to extract search criteria query string
suggestedFeatures Required User feedback for the extracted text body Model

Get global knowledge schema

This will update internal knowledge on schema and will try to extract nodes and associations using the given user feedback and prior knowledge. Extracted nodes and associations are not added to the graph.


URL Structure : /api/knowledge/criteria

Method : PUT

Parameters :

Parameters Value Description Parameter Type Data Type
text Required Text to extract search criteria query string
suggestedFeatures Required User feedback for the extracted text body Model