Intro

Welcome to the Core APIs User Guide, contained is an in-depth set of instructions to fully set up, configure, and trigger the product so you can start your Knowledge Graph exploration. The Core APIs is a collection of tools providing the ability to easily perform complex queries, analysis, and traversal against any Knowledge Graph, for use by any developer even with no prior Knowledge Graph experience. It can even be used for building user interfaces or as a basis for integration with other services in your architecture. The Core APIs is a lightweight, platform-agnostic tool with support for all common Knowledge Graphs using W3C Semantic Web Standards SPARQL 1.1 query language.

Contents

Configuring the Core APIs

The Core APIs has been designed to be entirely configurable through the use of Environment Variables. How to declare these environment variables will differ slightly depending on how you choose to run the product, which will be covered in the subsequent sections. As for the configuration variables themselves, they are all straight forward and easy to understand.

Knowledge Graph Configuration

The first configuration options are concerning the Knowledge Graph you wish to query and traverse.

• The Triplestore Endpoint <TRIPLESTORE_ENDPOINT> is the endpoint for your Triple Store that you want the Core APIs to connect to.

• The Triplestore Type <TRIPLESTORE_TYPE> is the type of your Triple Store. The Core APIs support for all common Knowledge Graphs, some graphs will support the default sparql type (e.g. AllegroGraph), however certain graphs require specific type declaration, these include neptune, rdfox, graphdb, stardog, and blazegraph.

• If your triplestore has authentication, the Triplestore Username <TRIPLESTORE_USERNAME> is the username for your Triple Store. This option may be left blank if authentication is not required.

• As with the username, the Triplestore Password <TRIPLESTORE_PASSWORD> is the password for your Triple Store. This can also be left blank if authentication is not required.

Core APIs Configuration

These next configuration options are involved with the running of the Core APIs itself.

• The Core APIs Username <CORE_API_USER> and Password <CORE_API_PASSWORD> are credentials you can provide to make the product require authentication when being triggered.

Running the Core APIs

The Core APIs, similar to the Lenses of Data Lens, is designed and built to be versatile, allowing them to be set up and ran on a number of environments, including in cloud or on-premise. This is achieved through the use of Docker Containers. In addition to this, we now have full support for the Amazon Web Services Marketplace, where you can directly subscribe to and run your Core APIs container from.

Running via AWS Marketplace

As previously mentioned, we now have full support for the Amazon Web Services Marketplace, this being the most straight forward way to get started with the Core APIs. Using our CloudFormation Templates linked to the provided Quick Create Stack, you can deploy a one-click solution to run the product.

This Quick Create Stack will start up an ECS Cluster with all the required permissions and networking, with the Core APIs running within as a task. All that is required is that you provide the configuration variables as described in the previous section, then once complete, click on the Create Stack button.

Open

Running via a Docker Image on AWS

In addition to the preconfigured stack created by the CloudFormation template, you also have the ability to run the Core APIs in your own new or existing AWS environment.

1. To do this first ensure you have an AWS ECS Cluster running, please ensure that it is in the same VPC as your Knowledge Graph if it is also running in AWS.

2. Next, you must create a Task Definition containing the Core APIs container image.

   1. This is done by selecting the Create New Task Definition button selecting a Launch Type Compatibility of either FARGATE or EC2.

   2. Next, provide the task with a name and create an IAM Task Role that grants permission for your container to call RegisterUsage, as defined in the following code. You must supply this IAM role in the Task Role parameter of the Amazon ECS task or Amazon EKS pod definition.

      { "Version": "2012-10-17", "Statement": [ { "Action": [ "aws-marketplace:RegisterUsage" ], "Effect": "Allow", "Resource": "*" } ] }

       

   3. Then add the container, this is where you specify the Docker Container image location, along with exposed ports and environment variables. To retrieve the image URI, select the View Container Image Details link on the Core API’s Marketplace Product Launch page. For the port mappings, provide the values of 8080 for both host and container ports, then for the environment variables, provide them as explained in the configuration section about and as shown in the image below. In addition, it is recommended you enable logging by checking the Auto-configure CloudWatch Logs box.

      Open

      

       

   4. Now that the Task Definition has been created, you may start the new task from within your ECS cluster.

Running via a Local On-Prem Docker Image

If you wish to run the Core APIs locally on-prem, first please ensure you have Docker installed, and contact us for access to the image and a production license. Then simply by running a command with the following structure, docker will start the container and run the Core APIs from your downloaded image.

For UNIX based machines (macOS and Linux):

For Windows

The above examples demonstrate how to override configuration options using environment variables in your Core APIs Container. Lines 6 and 7 show the use of passing in an environment variable saved to the machine, this can be helpful if you do not want credentials in the terminal history. Whereas lines 2-5 simply show string values being passed into the container. Given the Core APIs is ran on port 8080, line 10 exposes and binds that port of the host machine so that the APIs can be triggered. Lines 8 and 9 are additional configuration options for logging that can be set to be the same as above. And finally, line 9 is the name and version of the Docker image you wish to run.

For more information of running Docker Images, see the official Docs.

Calling the Core APIs

The Core APIs is a collection of tools providing the ability to easily perform complex queries, analysis, and traversal against any Knowledge Graph. These tools are split up into separate APIs within the Core APIs, all of which can be triggered via an exposed endpoint and by providing the necessary query parameters and authentication headers.

Retrieving the address of your stack varies depending on how you setup the Core APIs. If spun up using the CloudFormation template on AWS Marketplace, then the address can be found in the Outputs tab of the CloudFormation Stacks Console. If spun up manually in AWS ECS, then you can access the ip address via Core APIs Task running within the Cluster, ensure to include the port 8080. And if spun up locally, then the http://localhost:8080 address can be used.

To test your target address as well as the health of your Core APIs stack, you can called a GET request on <core-apis-address>/register-usage/actuator/health.

To use the Core APIs, the components are as follows:

Collection API

The Collection API allows a user to retrieve a list of any class type from your Knowledge Graph, also with support for powerful filtering. 

Resource API

The Resource API allows a user to retrieve every edge and value connected to a specific node in your Knowledge Graph.

Path API

The Path API allows a user to find the shortest path between two nodes in your Knowledge Graph, either directly or via a specified third node.

Suggest API

The Suggest API allows the user to find nodes by their label within your Knowledge Graph, also with support for powerful type filtering.