REST Ingestion

Since Visallo is a webapp, it has specific endpoints that you can use to develop your own REST clients.

Add Vertex

Setup

Before ingesting any data into Visallo, You need to create a user that will be the user with which you can ingest data. You will then be allowed to get a token that will authenticate you as that user so that it can ingest data. In the next curl requests it is assumed that you have already created a user 'ingester' with a password of 'password' and the Visallo webapp is running at 'https://myvisalloinstance'. It is also assumed that you know a little about the curl command so we can interact with Visallo from the command line using these REST calls. Visallo does use cookies in order to do authentication so your client will need to be able to handle cookies. It is possible to use any REST client you want by simply parsing what the curl command is doing and writing your own code so if you create a rest client that we do not have, please feel free to contribute it back to open source Visallo.

curl -XPOST -k -c visallo.cookie --data 'username=ingester&password=password' 'https://myvisalloinstance/login'

If you get a 200 from this request you are logged in, but you now need to get your token. In order to get your token you will need to find in your user profile. To get your user profile, you can call:

curl -k -b visallo.cookie 'https://myvisalloinstance/user/me'

The response to the previous curl command will return a JSON object that looks like:

{
  "id":"USER_2eda8db914444d0e81ef80b46171126a",
  "userName":"ingester",
  "displayName":"ingester",
  "userType":"USER",
  "status":"OFFLINE",
  "csrfToken":"j14550q5fefauq6bf8f88jnv",
  "privileges":["READ","EDIT","PUBLISH","ADMIN","COMMENT"],
  "uiPreferences":{},
  "authorizations":[],
  "longRunningProcesses":[],
  "workspaces":[],
  "properties":{"http://visallo.org/user#roles":"ADMIN"}
}

Create Vertex

Inside of the JSON Object that is returned, you can see that the CSRF token is j14550q5fefauq6bf8f88jnv. Your token will likely be different, but we will use this token in the future code examples.

Now we want to create an element. We need to specify a couple of parameters inside of the rest requests:

  • CSRFToken: the csrf token from the previous request
  • vertexId: the new vertex id
  • conceptType: the concept type of the new vertex
  • visibilitySource: the visibilitySource of the new vertex
  • properties: a json object of the properties that will be added to the new vertex
  • publish: a flag that will automaticaly publish the vertex

The resulting command is going to look like the following

curl -XPOST -k -b visallo.cookie --data 'csrfToken=j14550q5fefauq6bf8f88jnv&vertexId=email1&conceptType=http://visallo.org/sample#emailAddress&visibilitySource=&properties={"properties":[{"propertyName":"http://visallo.org#title","value":"testemail@email.com","propertyKey":""}]}&publish=true' 'https://myvisalloinstance/vertex/new'

The reqeust will return the full vertex object to you on the command line for your use if necessary.

Add a vertex property

Adding a property to a vertex is slightly different and required a workspace Id in order to update the vertex. This is currently a limitation of Visallo that will be addressed in the upcoming versions of Visallo. The vertex will be updated in the workspace, but will then allow you to publish the changes.

Creating a workspace

curl -XPOST -H 'Visallo-CSRF-Token: tm7vg2o5miv40qmkmdj9rkp4' -k -b visallo.cookie 'https://myvisalloinstance/workspace/create'

and as a response you will get some JSON that looks like the following. Pull the new workspace id out of the response and use it in the next request in order to change the property in the workspace.

{
  "workspaceId":"WORKSPACE_3843b8aa679943d1a8f2d19c00775ee3",
  "title":"Default - ingester",
  "createdBy":"USER_2eda8db914444d0e81ef80b46171126a",
  "users":[{"userId":"USER_2eda8db914444d0e81ef80b46171126a",
  "access":"WRITE"}],
  "vertices":[],
  "active":false,
  "sharedToUser":false,
  "editable":true,
  "commentable":true
}

Pull the workspace Id out of the response and use it in the next request

Set property

curl -XPOST -H 'Visallo-CSRF-Token: 3fasl51bsqtr6ub5v3j8fgc' -H 'Visallo-Workspace-Id:WORKSPACE_3843b8aa679943d1a8f2d19c00775ee3' -k -b visallo.cookie -d 'graphVertexId=email1&propertyName=http://visallo.org#title&value=updated title&visibilitySource=&justificationText=&metadata={}' 'https://myvisalloinstance/vertex/property'

Once the request is made, you will get a repsonse similar to the one that is given back when you created the vertex. The important part is the property that is marked private after you have changed it. This indicates that it has been changed in the workspace:

...,
{
"sandboxStatus":"PRIVATE",
"key":"45bf670a162c4586bee4012f314384ed",
"name":"http://visallo.org#title",
"streamingPropertyValue":false,
"metadata":{"http://visallo.org#modifiedDate":1476716428012,
"http://visallo.org#modifiedBy":"USER_2eda8db914444d0e81ef80b46171126a",
"http://visallo.org#visibilityJson":{"source":"",
"workspaces":["WORKSPACE_3843b8aa679943d1a8f2d19c00775ee3"]},
"http://visallo.org#justification":{"justificationText":""},
"http://visallo.org#confidence":0.5},
"value":"updated title",
"addable":true,
"updateable":true,
"deleteable":true
},
...

We will need the key for the next request so grab the key and put it in the publishData in the next request for publishing the property.

Publish property

curl -XPOST -H 'Visallo-CSRF-Token: 3fasl51bsqtr6ub5v3j8fgc' -H 'Visallo-Workspace-Id:WORKSPACE_3843b8aa679943d1a8f2d19c00775ee3' -k -b visallo.cookie -d 'publishData=[{"type":"property","key":"45bf670a162c4586bee4012f314384ed","name":"http://visallo.org#title","action":"update","status":"PRIVATE","vertexId":"email1"}]' 'https://myvisalloinstance/workspace/publish'

If everything went well, you will get a json response:

{"failures":[],"success":true}

results matching ""

    No results matching ""