Administration via HTTP with curl¶

What’s in this document?

Cluster group management
Cluster monitoring
Infrastructure monitoring
Location management
Repository SHACL validation
Saved queries
Security management
SPARQL template management
SQL views management
Authentication
Structures monitoring

This page describes GraphDB REST API calls for system administration as cURL commands, which lets developers script these calls in their applications.

See also the Help ‣ REST API view of the GraphDB Workbench where you will find a complete reference of all REST APIs and be able to run API calls directly from the browser.

In addition to this, the RDF4J API is also available.

Cluster group management ¶

Get cluster config

GET /rest/cluster/config

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/cluster/config'

Get cluster group status

GET /rest/cluster/group/status

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/cluster/group/status'

Get cluster node status

GET /rest/cluster/node/status

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/cluster/node/status'

Create cluster group

POST /rest/cluster/config

Example:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "electionMinTimeout": 7000,
   "electionRangeTimeout": 5000,
   "heartbeatInterval": 2000,
   "messageSizeKB": 64,
   "nodes": [
     "string"
   ],
   "verificationTimeout": 1500
 }' '<base_url>/rest/cluster/config'

Add cluster node

POST /rest/cluster/config/node

Example:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "nodes": [
     "string"
   ]
 }' '<base_url>/rest/cluster/config/node'

Update cluster group properties

PATCH /rest/cluster/config

Example:

curl -X PATCH --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "electionMinTimeout": 7000,
   "electionRangeTimeout": 5000,
   "heartbeatInterval": 2000,
   "messageSizeKB": 64,
   "verificationTimeout": 1500
 }' '<base_url>/rest/cluster/config'

Delete cluster group

DELETE /rest/cluster/config

Example:

curl -X DELETE --header 'Accept: application/json' '<base_url>/rest/cluster/config?force=false'

Delete cluster node

DELETE /rest/cluster/config/node

Example:

curl -X DELETE --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
   "nodes": [
     "string"
   ]
 }' '<base_url>/rest/cluster/config/node'

Cluster monitoring ¶

Get cluster statistics

GET /rest/monitor/cluster

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/monitor/cluster'

Infrastructure monitoring ¶

Get all infrastructure statistics

GET /rest/monitor/infrastructure

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/monitor/infrastructure'

Location management ¶

Most location management queries can either take the following set of attributes as an argument or return them as a response.

active (boolean): True if the location is the currently active one – the local location is the only location that can be active at any given point.
defaultRepository (string): Default repository for the location.
errorMsg (string): Error message, if there was an error connecting to this location.
label (string): Human readable label
local (boolean): True if the location is local (on the same machine as the Workbench).
password (string): Password for the new location if any. This parameter only makes sense for remote locations.
system (boolean): True if the location is the system location.
uri (string): The GraphDB location URL.
username (string): Username for the new location if any. This parameter only makes sense for remote locations.

Get all connected GraphDB locations

GET /rest/locations

Example:

curl <base_url>/rest/locations

Modify settings for a connected GraphDB location

POST /rest/locations

Example:

curl -X POST <base_url>/rest/locations -H 'Content-Type: application/json' -d '
    {
        "username": "<username>",
        "password": "<password>",
        "uri": "<location_uri>"
    }'

Connect to a remote GraphDB location

PUT /rest/locations

Example:

curl -X PUT <base_url>/rest/locations -H 'Content-Type: application/json' -d '
    {
        "username": "<username>",
        "password": "<password>",
        "uri": "<location_uri>"
    }'

Disconnect a GraphDB location

DELETE /rest/locations

Example:

curl -X DELETE <base_url>/rest/locations?uri=<encoded_location_uri>

Set the default repository

POST /rest/locations/active/default-repository

Example:

curl -X POST <base_url>/rest/locations/active/default-repository -H 'Content-Type: application/json' -d '
{
    "repository": "<repo_id>"
}'

Repository SHACL validation ¶

You can use the endpoints outlined below to trigger bulk validation on the repository.

Warning

This functionality is broken in 10.3.0 and was fixed 10.3.1.
Using custom named graphs for shapes does not work and will be fixed in a future version.

Validate data from the repository, identified by repositoryID with the shapes stored in a repository, identified by shapesRepositoryID:

POST: /rest/repositories/{repositoryID}/validate/repository/{shapesRepositoryID}

Example:

curl -X POST http://localhost:7200/rest/repositories/data-repo/validate/repository/shacl-reco

Validate data from the repository, identified by repositoryID, with the shapes you send in the request:

POST: /rest/repositories/{repositoryID}/validate/text

You can send the shapes as a part of the cURL command the following way:

Example:

curl -X POST -H "Content-Type: text/turtle"\
    --data-raw "@prefix ex: <http://example.org/ns#> .
                @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
                @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
                @prefix schema: <http://schema.org/> .
                @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
                ex:Aerith a schema:Person ;
                          schema:age \"Two\" ."\
    http://localhost:7200/rest/repositories/data-repo/validate/text

Alternatively, you can send it as a file instead:

Example:

curl -X POST -H "Content-Type: text/turtle"\
    --data-binary "@data.ttl"\
    http://localhost:7200/rest/repositories/data-repo/validate/text

Saved queries ¶

Get saved query (or queries, if no parameter specified)

GET /rest/sparql/saved-queries

Example:

curl <base_url>/rest/sparql/saved-queries?name=<query_name>

Create a new saved query

POST /rest/sparql/saved-queries

Example:

curl -X POST <base_url>/rest/sparql/saved-queries -H 'Content-Type: application/json' -d '
{
    "body": "<query_body>",
    "name": "<query_name>"
}'

Edit an existing saved query

PUT /rest/sparql/saved-queries

Example:

curl -X PUT <base_url>/rest/sparql/saved-queries -H 'Content-Type: application/json' -d '
{
    "body": "<query_body>",
    "name": "<query_name>"
}'

Delete an existing saved query

DELETE /rest/sparql/saved-queries

Example:

curl -X DELETE <base_url>/rest/sparql/saved-queries?name=<query_name>

Security management ¶

Check if security is enabled

GET /rest/security

Example:

curl <base_url>/rest/security

Enable security

POST /rest/security

Example:

curl -X POST --header 'Content-Type: application/json' -d true <base_url>/rest/security

Check if free access is enabled

GET /rest/security/free-access

curl <base_url>/rest/security/free-access

Enable or disable free access

POST /rest/security/free-access

Example:

curl -X POST --header 'Content-Type: application/json' -d '
    {
        "appSettings": {
              "DEFAULT_SAMEAS": boolean,
              "DEFAULT_INFERENCE": boolean,
              "EXECUTE_COUNT": boolean,
              "IGNORE_SHARED_QUERIES": boolean
              },
        "authorities": ["string"],
        "enabled": boolean
    }'  '<base_url>/rest/security/free-access'

Get all users

GET /rest/security/users

Example:

curl <base_url>/rest/security/users

Get a user

GET /rest/security/users/<username>

Example:

curl <base_url>/rest/security/users/<username>

Delete a user

DELETE /rest/security/users/<username>

Example:

curl -X DELETE <base_url>/rest/security/users/<username>

Change settings for a user

PATCH /rest/security/users/<username>

Example:

curl -X PATCH --header 'Content-Type: application/json' -d '
    {
        "appSettings": {
              "DEFAULT_SAMEAS": boolean,
              "DEFAULT_INFERENCE": boolean,
              "EXECUTE_COUNT": boolean,
              "IGNORE_SHARED_QUERIES": boolean
              },
        "password": "string"
   }'   '<base_url>/rest/security/users/<username>'

Create a user

POST /rest/security/users/<username>

Example:

curl -X POST --header 'Content-Type: application/json' -d '
    {
        "appSettings": {
              "DEFAULT_SAMEAS": boolean,
              "DEFAULT_INFERENCE": boolean,
              "EXECUTE_COUNT": boolean,
              "IGNORE_SHARED_QUERIES": boolean
              },
        "grantedAuthorities": ["string"],
        "username": "string",
        "password": "string"
    }'  '<base_url>/rest/security/users/<username>'

Edit a user

PUT /rest/security/users/<username>

Example:

curl -X PUT --header 'Content-Type: application/json' -d '
    {
        "appSettings": {
              "DEFAULT_SAMEAS": boolean,
              "DEFAULT_INFERENCE": boolean,
              "EXECUTE_COUNT": boolean,
              "IGNORE_SHARED_QUERIES": boolean
              },
        "grantedAuthorities": ["string"],
        "username": "string",
        "password": "string"
    }'  '<base_url>/rest/security/users/<username>'

SPARQL template management ¶

Create, edit, delete, and execute SPARQL templates, as well as to view all templates and their configuration.

Get IDs of all configured SPARQL templates per current repository

GET /rest/repositories/<repo_id>/sparql-templates

Example:

curl '<base_url>/rest/repositories/<repo_id>/sparql-templates'

Get a SPARQL template configuration

GET /rest/repositories/<repo_id>/sparql-templates/configuration

Example:

curl -X GET --header 'Accept: text/plain' '<base_url>/rest/repositories/<repo_id>/sparql-templates/configuration?templateID=<template_id>'

Create a new SPARQL template

POST /rest/repositories/<repo_id>/sparql-templates

Example:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: */*' -d '{
    "query": "<update_query_string> }",
    "templateID": "<template_id>"
}' '<base_url>/rest/repositories/<repo_id>/sparql-templates'

Delete an existing SPARQL template

DELETE /rest/repositories/<repo_id>/sparql-templates

Example:

curl -X DELETE --header 'Accept: */*' '<base_url>/rest/repositories/<repo_id>/sparql-templates?templateID=<template_id>'

Edit an existing SPARQL template

PUT /rest/repositories/<repo_id>/sparql-templates

Example:

curl -X PUT --header 'Content-Type: text/plain' --header 'Accept: */*' -d '<update query_string> ' '<base_url>/rest/repositories/<repo_id>/sparql-templates?templateID=<template_id>'

Execute an existing SPARQL template

POST /rest/repositories/<repo_id>/sparql-templates/execute

Example (based on this data):

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
     "sugar" : "none" ,
     "year" : 2020 ,
     "s" : "http://www.ontotext.com/example/wine#Blanquito"
 }' '<base_url>/rest/repositories/<repo_id>/sparql-templates/execute'

SQL views management ¶

Access, create, and edit SQL views (tables), as well as delete existing saved queries and see all SQL views for the active repository.

Get all SQL view names for current repository

GET /rest/sql-views/tables

Example:

curl -X GET --header 'Accept: application/json' --header 'X-GraphDB-Repository: <repoID>' '<base_url>/rest/sql-views/tables'

Get a SQL view configuration

GET /rest/sql-views/tables/<name>

Example:

curl -X GET --header 'Accept: application/json' --header 'X-GraphDB-Repository: <repoID>' '<base_url>/rest/sql-views/tables/<name>'

Create a new SQL view

POST /rest/sql-views/tables/

Example:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: */*' --header 'X-GraphDB-Repository:<repoID> -d '{
    "name": "string",
    "query": "string",
    "columns": ["string"]
    }'
    <base_url>/rest/sql-views/tables/

Edit an existing SQL view

PUT /rest/sql-views/tables/<name>

Example:

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: */*' --header 'X-GraphDB-Repository:<repoID>' -d '{
    "name": "string",
    "query": "string",
    "columns": ["string"]
    }'
    <base_url>/rest/sql-views/tables/<name>

Delete an existing saved query

DELETE /rest/sql-views/tables/<name>

Example:

curl -X DELETE <base_url>/rest/sql-views/tables/<name>

Authentication ¶

Obtain a GDB token in exchange for username and password

POST /rest/login/**

Example:

curl <base_url>/rest/login/<username> -X POST -H 'X-GraphDB-Password: <password>'

This command will return the user’s roles and GraphDB applications settings. It will also generate a GDB token, which is returned in an Authorization header and will be used at every next authentication request.

Structures monitoring ¶

Get structures statistics

GET /rest/monitor/structures

Example:

curl -X GET --header 'Accept: application/json' '<base_url>/rest/monitor/structures'