Location and repository management with the Workbench REST API

The GraphDB Workbench REST API can be used for managing locations and repositories programmatically. It includes connecting to remote GraphDB instances (locations), activating a location, and different ways for creating a repository. This tutorial shows how to use cURL command to perform basic location and repository management through the Workbench REST API.

Prerequisites

  • One or optionally two machines with Java.

  • One GraphDB instance:

  • Another GraphDB instance (optional, needed for the Attaching a remote location example):

    • Start GraphDB Free, SE, or EE on the second machine.

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

Hint

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

  • http://192.0.2.1:7200/ for the first instance;

  • http://192.0.2.2:7200/ for the second instance.

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

Managing repositories

Create a repository

Repositories can be created by providing a .ttl file with all the configuration parameters.

  1. Download the sample repository config file repo-config.ttl.

  2. Send the file with a POST request using the following cURL command:

    curl -X POST\
        http://192.0.2.1:7200/rest/repositories\
        -H 'Content-Type: multipart/form-data'\
        -F "config=@repo-config.ttl"
    

Note

You can provide a parameter location to create a repository in another location, see Managing locations below.

List repositories

Use the following cURL command to list all repositories by sending a GET request to the API:

curl -G http://192.0.2.1:7200/rest/repositories\
    -H 'Accept: application/json'

The output shows the repository repo1 that was created in the previous step.

[
   {
      "id":"repo1",
      "title":"my repository number one",
      "uri":"http://192.0.2.1:7200/repositories/repo1",
      "type":"free",
      "sesameType":"graphdb:FreeSailRepository",
      "location":"",
      "readable":true,
      "writable":true,
      "local":true
   }
]

Managing locations

Attach a location

Use the following cURL command to attach a remote location by sending a PUT request to the API:

curl -X PUT http://192.0.2.1:7200/rest/locations\
    -H 'Content-Type:application/json'\
    -d '{
        "uri": "http://192.0.2.2:7200/",
        "username": "admin",
        "password": "root"
    }'

Note

The username and password are optional.

Activate a location

Use the following cURL command to activate the previously attached location by sending a POST request to the API:

  • Activate the location http://192.0.2.2:7200/ on http://192.0.2.1:7200/:

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

Note

The default GraphDB location (stored locally on disk) is already activated by default. Activating an already active location is not an error. Note also that activating a location is not required for managing it through the REST API as an explicit location can be provided as a parameter to all REST API calls.

List locations

Use the following cURL command to list all locations that are attached to a machine by sending a GET request to the API:

curl http://192.0.2.1:7200/rest/locations\
    -H 'Accept: application/json'

The output shows one local and one remote location:

[
   {
      "system" : true,
      "errorMsg" : null,
      "active" : false,
      "defaultRepository" : null,
      "local" : true,
      "username" : null,
      "uri" : "",
      "password" : null,
      "label" : "Local"
   },
   {
      "system" : false,
      "errorMsg" : null,
      "active" : true,
      "defaultRepository" : null,
      "local" : false,
      "username" : "admin",
      "uri" : "http://192.0.2.1:7200/",
      "password" : "root",
      "label" : "Remote (http://192.0.2.1:7200/)"
   }
]

Note

If you skipped the “Attaching a remote location” step or if you already had other locations attached, the output will look different.

Detach a location

Use the following cURL command to detach a location from a machine by sending a DELETE request to the API:

  • To detach the remote location http://192.0.2.1:7200/:

    curl -G -X DELETE http://192.0.2.1:7200/rest/locations\
        -H 'Content-Type:application/json'\
        -d uri=http://192.0.2.2:7200/
    

Important

Detaching a location simply removes it from the Workbench and will not delete any data. A detached location can be re-attached at any point.

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 menu.