facebook pixel image Java REST API Wrapper Introduction

Java REST API Wrapper Introduction

The Visallo web interface was written as a single page application, as a side effect of this all interactions with the web server are performed using a REST API. You can view the code that backs the API here.

Visallo web application plugins can also extend or override the API as seen in the dev tools here, but we won’t cover that in this post. In this introduction I want to focus on using the Java REST API wrapper objects to interact with Visallo.

The Java REST API wrappers are partially generated using Swagger with an extra layer of convenience layered on top. To use them you can add the following to your Maven project:

<dependencies>
  <dependency>
    <artifactId>visallo-client-api</artifactId>
    <groupId>org.visallo</groupId>
    <version>1.1-SNAPSHOT</version>
  </dependency>
</dependencies>

<repositories>
    <repository>
        <id>v5analytics</id>
        <url>https://mvn.v5analytics.com/content/groups/org.visallo</url>
    </repository>
    <repository>
        <id>v5analytics-snapshots</id>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>interval:60</updatePolicy>
        </snapshots>
        <url>https://mvn.v5analytics.com/content/groups/org.visallo-snapshots</url>
    </repository>
    <repository>
        <id>v5analytics-public</id>
        <url>https://mvn.v5analytics.com/content/groups/public</url>
    </repository>
    <repository>
        <id>v5analytics-snapshots-public</id>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>interval:60</updatePolicy>
        </snapshots>
        <url>https://mvn.v5analytics.com/content/groups/public-snapshots</url>
    </repository>
</repositories>

Similar to how the web interface works we’ll need to login and get a workspace. We can do this using one
of the authentication providers. In this case we’ll be using the user name only authentication provider
for testing. The client API has a wrapper for this type of authentication:
org.visallo.web.clientapi.UserNameOnlyVisalloApi. To create one we’ll need a base URL and a user name.
The last parameter to the UserNameOnlyVisalloApi constructor will enable SSL certificate checking, and
since we’ll be running locally we’ll ignore the certificate errors by passing in true. We’ll also call
the login method and get a handle to the user’s workspace.

UserNameOnlyVisalloApi visalloApi = new UserNameOnlyVisalloApi("https://localhost:8889/", "testuser", true);
ClientApiWorkspace workspace = visalloApi.loginAndGetCurrentWorkspace();

The Visallo API object (in this case the UserNameOnlyVisalloApi object which extends
org.visallo.web.clientapi.VisalloApi) is divided into categories similar to the REST API’s. The
categories are:

  • User - Get current user information, other users in the system, etc.
  • Workspace - Get a list of workspaces, get vertices and edges on a workspace, update the workspace with new vertices, publish and undo sandbox changes.
  • Vertex - Read, update, delete, and search vertices.
  • Edge - Read, update, delete edges.
  • Ontology - Read the ontology.
  • Long running process - Find or wait for a long running process created from other API calls.
  • Admin - Upload an ontology.

Lets start by adding a new vertex with some properties to our workspace. To create a vertex we need to
create some properties, in this case we’ll create a first name and last name. We’ll also need to tell
Visallo what type of vertex we are creating, in this case we’ll be creating a vertex representing a
person, this is done by setting the concept type to http://visallo.org/dev#person. We also need to
indicate the visibility, in our example we’ll use an empty string denoting that this vertex will be
visible to all users. Passing a null vertex id will cause the system to generate one for us.

// first name property
ClientApiAddElementProperties.Property firstNameProperty = new ClientApiAddElementProperties.Property()
        .setPropertyKey("clientApi")
        .setPropertyName("http://visallo.org/dev#firstName")
        .setValue("Joe")
        .setVisibilitySource("");

// last name property
ClientApiAddElementProperties.Property lastNameProperty = new ClientApiAddElementProperties.Property()
        .setPropertyKey("clientApi")
        .setPropertyName("http://visallo.org/dev#lastName")
        .setValue("Ferner")
        .setVisibilitySource("");

// create the vertex
String conceptType = "http://visallo.org/dev#person";
String visibilitySource = "";
String justificationText = "Vertex created using Client API wrapper";
String vertexId = null;
ClientApiAddElementProperties properties = new ClientApiAddElementProperties(
        firstNameProperty,
        lastNameProperty
);
ClientApiElement vertex = visalloApi.getVertexApi().create(
        conceptType,
        visibilitySource,
        justificationText,
        vertexId,
        properties
);

If you login to the website after running the above code you'll notice the vertex does not appear on your
workspace. But if you open the diff panel in the lower left you'll see a vertex and two properties have
been created. If you would like to add the vertex to your workspace you'll need to update the workspace.

ClientApiWorkspaceUpdateData workspaceUpdate = new ClientApiWorkspaceUpdateData();
workspaceUpdate.getEntityUpdates().add(
    new ClientApiWorkspaceUpdateData.EntityUpdate()
        .setVertexId(vertex.getId())
        .setGraphPosition(new GraphPosition(0, 0))
);
visalloApi.getWorkspaceApi().update(workspaceUpdate);

After refreshing your web browser you should now see a single vertex on your workspace. Lets publish the
vertex so all users can see our new vertex. To do this we’ll query for the list of diff items that need
to be published, then we’ll publish all of them.

List<ClientApiWorkspaceDiff.Item> diffItems = visalloApi.getWorkspaceApi().getDiff().getDiffs();
visalloApi.getWorkspaceApi().publishAll(diffItems);

Finally we need to logout to free up the session and any resources.

visalloApi.logout();