Location and Repository Management with the GraphDB REST API¶

What’s in this document?

Prerequisites
Managing repositories
- Create a repository
- List repositories
Managing locations
Further reading

The GraphDB 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 GraphDB REST API.

Prerequisites ¶

One or optionally two machines with Java.
One GraphDB instance:
- Start GraphDB on the first machine.
  
  Tip
  
  For more information on deploying GraphDB, please see Installing and Upgrading.
Another GraphDB instance (optional, needed for the Attaching a remote location example):
- Start GraphDB 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.

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

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:SailRepository",
      "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.

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.