Cluster management with the Workbench REST API

The GraphDB Workbench REST API can be used for managing a GraphDB EE cluster. It includes connecting workers to masters, connecting masters to each other, as well monitoring the state of a cluster. This tutorial shows how to use cURL commands to perform basic cluster management through the Workbench REST API.

This tutorial builds upon the Location and repository management with the Workbench REST API tutorial.

Prerequisites

  • Four machines with Java and Tomcat.

  • Three GraphDB EE Server instances to host one master and two worker repositories:

    Start GraphDB EE on all machines.

    Tip

    See Installing GraphDB EE for more information on installing GraphDB and setting up JMX.

  • One GraphDB EE Workbench instance to serve as a REST API endpoint:

    Start GraphDB EE (this can be done on your local machine too).

  • cURL command line tool for sending requests to the API.

Hint

Throughout the tutorial, the four instances will be referred to with the following URLs:

  • http://192.0.2.1:7200/, for the instance that will host the first worker;

  • http://192.0.2.2:7200/, for the instance that will host the second worker;

  • http://192.0.2.3:7200/, for the instance that will host the master;

  • http://192.0.2.4:7200/, for the Workbench instance.

Please adjust the URLs according to the IPs or hostnames of your own machines.

Creating a cluster

Attach the locations

To create a remote location, send a POST request to the REST API at http://192.0.2.4:7200/:

  1. Attach the location http://192.0.2.1:7200/

    curl -X POST http://192.0.2.4:7200/rest/locations\
        -H 'Content-Type:application/json'\
        -d '{
            "uri": "http://192.0.2.1:7200/"
        }'
    
  2. Attach the location http://192.0.2.2:7200/

    curl -X POST http://192.0.2.4:7200/rest/locations\
        -H 'Content-Type:application/json'\
        -d '{
            "uri": "http://192.0.2.2:7200/"
        }'
    
  3. Attach the location http://192.0.2.3:7200/:

    curl -X POST http://192.0.2.4:7200/rest/locations\
        -H 'Content-Type:application/json'\
        -d '{
            "uri": "http://192.0.2.3:7200/"
        }'
    

Inspect the result in the GraphDB Workbench by accessing the Setup -> Repositories view:

../../_images/rest-api-remote-locations.png

Note

Note that the first attached location has become active but that is irrelevant for this tutorial.

Create workers and master

After successfully attaching the three remote locations, you have to create the repositories.

First, download the sample repository config files master1-config.ttl, worker1-config.ttl, and worker2-config.ttl.

Then, create each repository by sending a POST request to the REST API at http://192.0.2.4:7200/:

  1. Create worker1 repository on http://192.0.2.1:7200/:

    curl -X POST\
        http://192.0.2.4:7200/rest/repositories?location=http://192.0.2.1:7200/\
        -H 'Content-Type: multipart/form-data'\
        -F "config=@worker1-config.ttl"
    
  2. Create worker2 repository on http://192.0.2.2:7200/:

    curl -X POST\
        http://192.0.2.4:7200/rest/repositories?location=http://192.0.2.2:7200/\
        -H 'Content-Type: multipart/form-data'\
        -F "config=@worker2-config.ttl"
    
  3. Create master1 repository on http://192.0.2.3:7200/:

    curl -X POST\
        http://192.0.2.4:7200/rest/repositories?location=http://192.0.2.3:7200/\
        -H 'Content-Type: multipart/form-data'\
        -F "config=@master1-config.ttl"
    

Connect workers to master

To connect the workers to the master, send POST requests for each worker:

  1. Connect worker1 with master1

    curl -X POST http://192.0.2.4:7200/rest/cluster/masters/master1/workers\
        -H 'Content-Type: application/json'\
        -d '{
            "workerURL": "http://192.0.2.1:7200/repositories/worker1",
            "masterLocation": "http://192.0.2.3:7200/"
        }'
    
  2. Connect worker2 with master1

    curl -X POST http://192.0.2.4:7200/rest/cluster/masters/master1/workers\
        -H 'Content-Type: application/json'\
        -d '{
            "workerURL": "http://192.0.2.2:7200/repositories/worker2",
            "masterLocation": "http://192.0.2.3:7200/"
        }'
    

After the successful execution of these requests you should be able to see the following in the Setup -> Cluster view in the GraphDB Workbench:

../../_images/rest-api-cluster.png

Further reading

For a full list of request parameters and more information regarding sending requests, check the REST API documentation within the GraphDB Workbench accessible from the Help ‣ REST API Documentation menu.