Managing repositories and locations via the GraphDB REST API¶
What’s in this document?
GraphDB’s REST API lets you perform basic location and repository management. This includes connecting to remote GraphDB instances (locations), activating a location, and managing local and remote repositories.
This page shows how to execute these requests with the curl command line utility. Most modern programming languages can execute HTTP requests like this either natively or with an available library. This lets you integrate these capabilities into your custom applications.
Note
The GraphDB command line utility storage-tool gives you several ways to work with GraphDB repositories from your operating system’s command line interface.
Managing repositories¶
Most repository management queries can either take the following set of attributes as an argument or return them as a response:
externalUrl(string): The URL where the repository can be accessed by an external serviceid(string): The repository IDlocal(boolean):Trueif the repository is local (on the same machine as Workbench)location(string): If remote, the repository’s locationtitle(string): The repository titletype(string): Repository type —graphdb,ontop, orfedxunsupported(boolean):Trueif the repository is unsupportedwritable(boolean):Trueif the repository is writablereadable(boolean):Trueif the repository is readableuri(string): The GraphDB location URL
Create a repository¶
GraphDB lets you create a repository with an API call that sends RDF data of the configuration information. (If using GraphDB Free, your instance can only have five repositories; see Creating a repository for more on this.) You can try this yourself with the following example.
Download the sample repository config file
repo-config.ttl.Send the file with a
POSTrequest using the followingcurlcommand:curl -X POST\ http://localhost:7200/rest/repositories\ -H 'Content-Type: multipart/form-data'\ -F "config=@repo-config.ttl"
List repositories¶
The following curl command lists all repositories by sending a GET request to the API:
curl http://localhost:7200/rest/repositories\
-H 'Accept: application/json'
The output shows one repository named repo1.
[
{
"id":"repo1",
"title":"my repository number one",
"uri":"http://localhost:7200/repositories/repo1",
"type":"free",
"sesameType":"graphdb:SailRepository",
"location":"",
"readable":true,
"writable":true,
"local":true
}
]
You can retrieve information about all the repositories at a remote location by including that location as a parameter:
curl http://localhost:7200/rest/repositories?location=http://192.168.0.79:7200
Retrieve information about one repository¶
The command to list repositories shown in the previous section will also list some information about all the repositories stored on the GraphDB instance at that URL. To retrieve more detailed information about a single repository, add the repository ID to the end of the URL that is used to list repositories:
curl http://localhost:7200/rest/repositories/repo1
As when listing repositories, adding a ?location parameter to the URL lets you retrieve information about one repository at the specified location.
Count the triples in a repository¶
Adding /size to the URL that request information about a repository asks for its size, measured in triples:
curl http://localhost:7200/rest/repositories/repo1/size
As when listing repositories, adding a ?location parameter to the URL lets you count the triples in a repository at the specified location.
Restart a repository¶
An HTTP POST request that names a specific repository and adds /restart at the end of that URL instructs the server to restart that repository:
curl -X POST http://localhost:7200/rest/repositories/repo1/restart
As when listing repositories, adding a ?location parameter to the URL will restart the named repository at that location.
Delete a repository¶
An HTTP DELETE request that names a specific repository instructs the server to delete that repository:
curl -X DELETE http://localhost:7200/rest/repositories/repo1
As when listing repositories, adding a ?location parameter to the URL will delete the named repository at that location, assuming that the appropriate write permissions are in place.
Edit a repository’s configuration¶
To edit a repository’s configuration, do an HTTP PUT of the new configuration stored as JSON, as shown in the following model.
Note
When editing the configuration of a local repository, omit the “location” parameter.
curl -X PUT <base_url>/rest/repositories/<repo_id> -H 'Accept: application/json' -H 'Content-Type: application/json' -d '
{
"id": "<repo_id>",
"location": "<location_uri>",
"title": "<repo_title>",
"type": "graphdb",
"sesameType":"graphdb:SailRepository",
"params":{
"queryTimeout":{
"name":"queryTimeout",
"label":"Query timeout (seconds)",
"value":"0"
},
"cacheSelectNodes":{
"name":"cacheSelectNodes",
"label":"Cache select nodes",
"value":"true"
},
"rdfsSubClassReasoning":{
"name":"rdfsSubClassReasoning",
"label":"RDFS subClass reasoning",
"value":"true"
},
"validationEnabled":{
"name":"validationEnabled",
"label":"Enable the SHACL validation",
"value":"true"
},
"ftsStringLiteralsIndex":{
"name":"ftsStringLiteralsIndex",
"label":"FTS index for xsd:string literals",
"value":"default"
},
"shapesGraph":{
"name":"shapesGraph",
"label":"Named graphs for SHACL shapes",
"value":"http://rdf4j.org/schema/rdf4j#SHACLShapeGraph"
},
"parallelValidation":{
"name":"parallelValidation",
"label":"Run parallel validation",
"value":"true"
},
"checkForInconsistencies":{
"name":"checkForInconsistencies",
"label":"Enable consistency checks",
"value":"false"
},
"performanceLogging":{
"name":"performanceLogging",
"label":"Log the execution time per shape",
"value":"false"
},
"disableSameAs":{
"name":"disableSameAs",
"label":"Disable owl:sameAs",
"value":"true"
},
"ftsIrisIndex":{
"name":"ftsIrisIndex",
"label":"FTS index for full-text indexing of IRIs",
"value":"en"
},
"entityIndexSize":{
"name":"entityIndexSize",
"label":"Entity index size",
"value":"10000000"
},
"dashDataShapes":{
"name":"dashDataShapes",
"label":"DASH data shapes extensions",
"value":"true"
},
"queryLimitResults":{
"name":"queryLimitResults",
"label":"Limit query results",
"value":"0"
},
"throwQueryEvaluationExceptionOnTimeout":{
"name":"throwQueryEvaluationExceptionOnTimeout",
"label":"Throw exception on query timeout",
"value":"false"
},
"member":{
"name":"member",
"label":"FedX repo members",
"value":[]
},
"storageFolder":{
"name":"storageFolder",
"label":"Storage folder",
"value":"storage"
},
"validationResultsLimitPerConstraint":{
"name":"validationResultsLimitPerConstraint",
"label":"Validation results limit per constraint",
"value":"1000"
},
"enablePredicateList":{
"name":"enablePredicateList",
"label":"Enable predicate list index",
"value":"true"
},
"transactionalValidationLimit":{
"name":"transactionalValidationLimit",
"label":"Transactional validation limit",
"value":"500000"
},
"ftsIndexes":{
"name":"ftsIndexes",
"label":"FTS indexes to build (comma delimited)",
"value":"default, iri, en"
},
"logValidationPlans":{
"name":"logValidationPlans",
"label":"Log the executed validation plans",
"value":"false"
},
"imports":{
"name":"imports",
"label":"Imported RDF files('\'';'\'' delimited)",
"value":""
},
"isShacl":{
"name":"isShacl",
"label":"Enable SHACL validation",
"value":"false"
},
"inMemoryLiteralProperties":{
"name":"inMemoryLiteralProperties",
"label":"Cache literal language tags",
"value":"true"
},
"ruleset":{
"name":"ruleset",
"label":"Ruleset",
"value":"rdfsplus-optimized"
},
"readOnly":{
"name":"readOnly",
"label":"Read-only",
"value":"false"
},
"enableLiteralIndex":{
"name":"enableLiteralIndex",
"label":"Enable literal index",
"value":"true"
},
"enableFtsIndex":{
"name":"enableFtsIndex",
"label":"Enable full-text search (FTS) index",
"value":"false"
},
"defaultNS":{
"name":"defaultNS",
"label":"Default namespaces for imports('\'';'\'' delimited)",
"value":""
},
"enableContextIndex":{
"name":"enableContextIndex",
"label":"Enable context index",
"value":"false"
},
"baseURL":{
"name":"baseURL",
"label":"Base URL",
"value":"http://example.org/owlim#"
},
"logValidationViolations":{
"name":"logValidationViolations",
"label":"Log validation violations",
"value":"false"
},
"globalLogValidationExecution":{
"name":"globalLogValidationExecution",
"label":"Log every execution step of the SHACL validation",
"value":"false"
},
"entityIdSize":{
"name":"entityIdSize",
"label":"Entity ID size",
"value":"32"
},
"repositoryType":{
"name":"repositoryType",
"label":"Repository type",
"value":"file-repository"
},
"eclipseRdf4jShaclExtensions":{
"name":"eclipseRdf4jShaclExtensions",
"label":"RDF4J SHACL extensions",
"value":"true"
},
"validationResultsLimitTotal":{
"name":"validationResultsLimitTotal",
"label":"Validation results limit total",
"value":"1000000"}
}
}
}'
Tip
Adjust parameters with new values except for <repo_id> in order to edit the current repository configuration.
Managing locations¶
Tip
Throughout this document, the two example instances will be referred to with the following URLs:
http://192.0.2.1:7200/for the first instancehttp://192.0.2.2:7200/for the second instance
Adjust the URLs according to the IP or hostname values of your own machines.
Attach a location¶
This section describes how you can attach your locally running instance of GraphDB to another one on the same network.
The following curl command attaches the remote http://192.0.2.2:7200 GraphDB instance to the local http://192.0.2.1:7200 one by sending a PUT request to the API running on the local instance:
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 may not be necessary, depending on the settings of the remote location.
List locations¶
Use the following curl command to list all attached locations 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/)"
}
]
Detach a location¶
Use the following curl command to detach a remote location by sending a DELETE request to the API:
To detach the remote location
http://192.0.2.1:7200/:curl -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 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 about sending requests, check the REST API documentation within the GraphDB Workbench accessible from the menu.