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.

First, download the sample repository config file repo-config.ttl.

Then, 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 SYSTEM repository and the repository repo1 that was created in the previous step.

[
   {
      "id":"SYSTEM",
      "title":"System configuration repository",
      "uri":"http://192.0.2.1:7200/repositories/SYSTEM",
      "type":"system",
      "sesameType":"openrdf:SystemRepository",
      "location":"",
      "readable":true,
      "writable":true,
      "local":true
   },
   {
      "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",
        "superadminSecret": "secret"
    }'

Note

The username, password and superadminSecret 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 1 local location and 1 remote location:

[
   {
      "system" : true,
      "errorMsg" : null,
      "active" : false,
      "defaultRepository" : null,
      "superadminSecret" : null,
      "local" : true,
      "username" : null,
      "uri" : "",
      "password" : null,
      "label" : "Local"
   },
   {
      "system" : false,
      "errorMsg" : null,
      "active" : true,
      "defaultRepository" : null,
      "superadminSecret" : "secret",
      "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 it 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 the Help -> REST API Documentation menu.