Learn how to use the DFRNT API with the TerminusDB client

Welcome to this guide on connecting to DFRNT using with the JavaScript Client for TerminusDB! This article will walk you through the steps to use API tokens to connect to the TerminusDB teams hosted at DFRNT.

Connecting with the JavaScript and Python Clients

First things first, ensure you have installed the TerminusDB following the instructions for the JavaScript Client or the Python Client.

Connecting to DFRNT with the TerminusDB JavaScript Client

Depending on whether you are connecting to an instance you have set up yourself or using DFRNT in the cloud, there are two different methods of connection.

Loading the TerminusDB Client

In both cases, whether local or in the clould, you should load the TerminusDB client in your script with the following code, which includes all you need to work with content repositories in DFRNT:

const dfrntClient = require("@terminusdb/terminusdb-client");

Connecting to the DFRNT API Endpoint

The DFRNT endpoint has the form https://dfrnt.com/api/hosted/TEAM where TEAM is the name of the storage location team for the content repositories you want to access.

To connect to this TEAM, you will need to get your API key after selecting the team you want to use. Your built-in personal "team" has the form 00000000-0000-0000-0000-000000, which is also the same as your technical user name.

Creating a Client

To create a client, use the following code within your script, ensuring to use your credentials. Create an API token in the settings section and set a relevant timeout for it. The name for it will help understand where is it used, which is helpful for the future.

It is recommended to use environment variables for the API token to keep it secret and not accidentally commit it to code.

const dfrntClient = new TerminusClient.WOQLClient('https://dfrnt.com/api/hosted/00000000-0000-0000-0000-000000', {
    user: "myemail@example.com",
    organization: '00000000-0000-0000-0000-000000'
});

dfrntClient.setApiKey(process.env.MY_ACCESS_TOKEN);

Connecting to a DFRNT or TerminusDB Endpoint

Whether you are connecting to a local docker, a local server, or the cloud environment, you can use the following to log in to TerminusDB:

const client = new TerminusClient.WOQLClient(SERVER_URL, {
    user: "admin",
    key: "myKey"
});

async function getSchema() {
    client.db("DB_NAME");
    const schema = await client.getSchema();
}

Connect from the command line with curl

To quickly check the connection to DFRNT, you can also use the curl command line tool, as below (on Linux). Make sure to replace TEAM and API_TOKEN with the values from your profile at DFRNT.com. It should look something like below, where the authority part of the response mirrors back the IRI for the supplied team/user.

$ export TEAM=00000000-0000-0000-0000-000000
$ export API_TOKEN=0ad420...
$ curl -H "Authorization: Token $API_TOKEN" "https://dfrnt.com/api/hosted/$TEAM/api/info"
{
  "@type": "api:InfoResponse",
  "api:info": {
    "authority": "terminusdb://system/data/User/00000000-0000-0000-0000-000000",
    ...
    "api:status": "api:success"
  }
}

Note that the username can be different from the team when collaborating using invitations. The username connected to the user that created the token can be found in Settings > Profile section, as Current userid.

Using the GraphQL endpoint

Your content repository (data product) is available with a GraphQL endpoint as well. Copy the endpoint URL. For the the RustyGearsInc team it looks like below. It could also be a personal URL with the userid instead of RustyGearsInc.

https://dfrnt.com/api/hosted/RustyGearsInc

Then append the GraphQL portion to it so that the URL looks like this:

https://dfrnt.com/api/hosted/RustyGearsInc/api/graphql/RustyGearsInc/myDataProduct

Example GraphQL query:

$ export TEAM=00000000-0000-0000-0000-000000
$ export API_TOKEN=0ad420...
$ export REPO=myDataProduct
$ curl \
-H "Content-Type: application/json" \
-H "Authorization: Token $API_TOKEN" \
-d '{ "query": "query { Entity { label } }" }' \
"https://dfrnt.com/api/hosted/$TEAM/api/graphql/$TEAM/$REPO"

{
  "data": {
    "Entity": [
      {
        "label": "Rusty Gears"
      }
    ]
  }
}

Getting Started Tutorial

To get more help with the TerminusDB JavaScript Client, try out the Getting Started with the TerminusDB JavaScript Client five-part tutorial. It's a great way to familiarize yourself with the client and its capabilities using the TerminusDB documentation.