Skip to main content

Manage data using NodeJs and the JSON DB API tutorials

The JSON DB API allows users to access rich database functionality using JSON messages over HTTP(S) without any local binary dependencies.

While the API is easy to use, and writing a driver from scratch is simple, FairCom provides drivers for the most common programming languages to make usage even easier.

This section covers the NodeJs driver for the JSON DB API and explains how to use it.

The NodeJS driver for the JSON DB API makes requests using an HTTP client library as its only direct dependency.

Note

These procedures were written and tested using Windows 11 and Python 3.9.1.

Prerequisites:
  • Ensure the FairCom server is installed and that it is running.

  • Ensure that the latest version of NodeJs is installed and executable from a command line.

Establish FairCom DB server communications

  1. Inside the FairCom DB folder, open the SDK folder.

  2. Locate and open the drivers\nodejs.json.nav (or nodejs.json.db) in your command prompt.

  3. To install the node-fetch library, run > npm install.

  4. Run > cd examples.

  5. Run > node ping.js.

  6. Observe the ping successful message.

    myArgs:  [ 'ping' ]

    response: pong

    This indicates that your FairCom DB server is running, that the JSON DB API is accessible, and the NodeJS driver can communicate successfully with the server.

Create test data

  1. Run the following commands in order:

    1. node createDatabase.js

    2. node createTable.js

    3. node createIndex.js

    4. node insertRecords.js

    5. node getRecordsByTable.js

  2. Observe the results:

    [4, 13358, 'Ian Nepomniachtchi', 2789]
    [1, 13358, 'Magnus Carlsen', 2847]
    [2, 13358, 'Fabiano Caruana', 2820]
    [3, 13358, 'Ding Liren', 2791]
    [5, 13358, 'Levon Aronian', 2781]
    [6, 13358, 'Alexander Grischuk', 2777]
    [7, 13358, 'Anish Giri', 2776]
  3. Confirm the successful creation of the table inside the FairCom Data Explorer.

Example 1. Source code
const JNAClient = require('../JNAClient');
var jnaClient = new JNAClient("http://localhost:8080/api")

const dbName = "test_js";

async function createDB() {
  try {
    await jnaClient.login("ADMIN", "ADMIN");
    await jnaClient.createDatabase(dbName);
    console.log("created new db: " + dbName);
  } catch(error) {
    console.log(error);
  }
  await jnaClient.logout();
}
createDB();


  • In Example 1, “Source code, a new JNAClient is instantiated.

  • We pass in the URL of the server that runs the FairCom DB server. If you want to use HTTPS you need a real SSL certificate.

  • Attempt to login to the server using username and password ADMIN. This is the default and it should be changed for servers in production.

  • If the login was successful the high-level API function createDatabase inside of a try/catch/finally block is called.

  • If the call is successful a success message is printed.

  • If the call is NOT successful a JNAException is thrown and caught and a failure message is printed.

  • Finally, the logout function is called. This is important because the server caches a lot of resources associated with every session. Always make sure that you log out when you are done with the JSON DB API or that you keep the session alive using ping calls. A ping call once per minute should be enough for long-running tasks.

To look at the messages that are passed back and forth between the client and the server, specify your preference with the second parameter when calling JNAClient.

Example 2. jnaClient
var jnaClient = new JNAClient("http://localhost:8080/api", 3)


In the second parameter:
  • 1 means print client request

  • 2 means print server response

  • 3 prints both

  1. Create and open a new, empty folder named my_test.

  2. Run > npm init -y, using a command prompt, to create a package.json file with default values.

  3. Edit the package.json file to add a new section:

    "dependencies": {
        "node-fetch": "^2.6.7"
      }
  4. Copy JNAClient.js from the nodejs.json.nav (or nodejs.json.db) folder into the new folder.

  5. Create a new file named my_test.js.

  6. Open the my_test.js file in a text editor.

  7. Change my_test.js to:

    const JNAClient = require('./JNAClient');
    var jnaClient = new JNAClient("http://localhost:8080/api")
    
    async function ping() {
      try {
        await jnaClient.open();
    
        await jnaClient.ping();
        console.log("ping success.");
      
      } catch(error) {
        console.log(error);
      }
      jnaClient.close();
    }
    
    ping();
    
  8. Using the command prompt, run > node my_test.js.

  9. Observer the ping successful message:

    > ping successful.

    This indicates that you have successfully created your own project using the NodeJS driver for FairCom DB.