GraphDB Cloud REST APIs

Skip to end of metadata
Go to start of metadata
Table of Contents

Introduction

The Cognitive Cloud provides various REST APIs.

  • To use any of these APIs requires an API key for HTTP basic authentication. The API keys are private for each user account and can be generated via the Cognitive Cloud Management Console.
  • The RESTful services accept JSON as input and return JSON as output.
  • Cognitive Cloud services support gzip compression of the service's response. You can enable it by setting an Accept-Encoding: gzip HTTP header.

API Keys

The access to the Cognitive Cloud REST API requires a private API key, which consists of two randomly generated parts, the "key ID" and "password". Each customer account can generate an unlimited number of API keys (for different applications or users) and each API key can be enabled/disabled or deleted as necessary.

To create a new API key, go to the "API & Keys" section of the Cognitive Cloud Management Console at https://cloud.ontotext.com and click the "Create a new key" button.

Note: You must store the key ID and password at a secure location. For security purposes if you lose your API key password, you will not be able to recover it. You will need to delete your existing key and generate a new one.

Request HTTP headers. Request and Response Formats.

  • information about the fully managed database-as-a-service request/response formats is available on Fully Managed Database the page

GraphDB Cloud REST services support the following HTTP request methods:

Cognitive Cloud Service
GET
POST
PUT
DELETE
GraphDB Cloud
  • list repositories
  • list named graphs / contexts / namespaces
  • query data
  • read data
  • get the database configuration
  • query data
  • update data (RDF document)
  • update data (SPARQL 1.1 Update)
  • create repositories
  • create namespaces and contexts
  • update data (RDF document)
  • update the database configuration
  • delete repositories
  • delete named graphs
  • delete namespaces and contexts
  • delete data

SSL Encryption

All Cognitive Cloud REST APIs as well as the Cognitive Cloud Management Console utilize a transport level encryption via SSL.

HTTP Compression

All Cognitive Cloud services support gzip compression of the service response for better performance. You can enable the compression by setting an Accept-Encoding: gzip HTTP header.

Error messages

In case of a problem with the correct execution of the request, an error response is returned with an HTTP status code, specifying the type of the error (as described below), as well as a human readable error message.

Status Code
Description
40x Problems with the user input
50x Errors during the execution of the request

GraphDB Cloud API - Managing Repositories & Querying Data

Except where specified otherwise, all parameters are required.

Description Method Content-Type
URL
Parameters
Get information about the repositories available in the database
GET
N/A
/repositories
-
Send a SPARQL query to the repository as a query parameter
GET
N/A
/repositories/<REPOSITORY>
  • query - query parameter - the query to evaluate
  • infer (optional) - query parameter - specifies whether inferred statements should be included in the query evaluation. Defaults to true.
Send a SPARQL query to the repository as the body of a request
POST
application/www-form-urlencoded /repositories/<REPOSITORY>
  • query - the query to evaluate
  • infer (optional) - query parameter - specifies whether inferred statements should be included in the query evaluation. Defaults to true.
Create a new repository in the database. The configuration should be written in JSON.
An example configuration would be:

NOTE: this method is an extension specific to the Cognitive Cloud platform, and it is not originally available in the OpenRDF REST API.
PUT
application/json
/repositories/<REPOSITORY>
  • repositoryID - unique name for the repository (valid characters: alpha-numeric, dash, underscore)
  • label - Human readable repository description (optional)
  • ruleset - the inference type to be used by the repository engine. Valid values for the ruleset include:
    • none
    • rdfs-optimized
    • rdfs
    • owl-horst-optimized
    • owl-horst** owl-max-optimized** owl-max
    • owl2-ql-optimized
    • owl2-ql
    • owl2-rl-optimized
    • owl2-rl
  • base-URL - ...
  • enablePredicateList - use additional indexes for predicates. Default: false.
Delete a repository and its data from the database.
DELETE
N/A
/repositories/<REPOSITORY>  

Create, Read, Upload & Delete Data

Description Method
Content-Type
URL
Parameters
Fetches specific statements from the repository.
Will return all statements if request body is blank.
GET
application/www-form-urlencoded /repositories/<REPOSITORY>/statements
  • subj (optional) - restricts the GET operation to statements with the specified resource as subject
  • pred (optional) - restricts the GET operation to statements with the specified URI as predicate.
  • obj (optional) - restricts the GET operation to statements with the specified value as object
  • context (optional) - If specified, restricts the operation to one or more specific contexts in the repository
  • infer (optional) - Specifies whether inferred statements should be included in the result of GET requests. Inferred statements are included by default. Specifying any value other than "true" (ignoring case) restricts the request to explicit statements only
Updates data in the repository. The request body is expected to contain either an RDF document, a SPARQL 1.1 Update string, or a special purpose transaction document.
  • If an RDF document is supplied, the statements found in the RDF document will be added to the repository.
  • If a SPARQL 1.1 Update string is supplied, the update operation will be parsed and executed.
  • If a transaction document is supplied, the updates specified in the transaction document will be executed
POST
RDF: depends on format

SPARQL: application/www-form-urlencoded
/repositories/<REPOSITORY>/statements
  • baseURI (optional) Specifies the base URI to resolve any relative URIs found in uploaded data against
  • update (optional) - specifies the SPARQL 1.1 Update string to be executed. The value is expected to be a syntactically valid SPARQL 1.1 Update string
Replaces all data in the with the supplied data. The data supplied with the request is expected to contain a valid RDF document.
PUT
Depends on the RDF format
/repositories/<REPOSITORY>/statements
  • baseURI (optional) Specifies the base URI to resolve any relative URIs found in uploaded data against
Deletes statements from the repository.
Will delete all statements if request body is blank.
DELETE
N/A
/repositories/<REPOSITORY>/statements
  • subj (optional) - restricts the DELETE operation to statements with the specified resource as subject
  • pred (optional) - restricts the DELETE operation to statements with the specified URI as predicate.
  • obj (optional) - restricts the DELETE operation to statements with the specified value as object
  • context (optional) - If specified, restricts the operation to one or more specific contexts in the repository

Working with Named Graphs

Description Method
URL
Parameters
Gets information on the named graphs in the repository.
GET
/repositories/<REPOSITORY>/rdf-graphs -
Fetches statements from the named graph.
GET
/repositories/<REPOSITORY>/rdf-graphs/<GRAPH> -
Updates data in the named graph in the repository, replacing any existing data in the named graph with the supplied data. The data supplied with this request is expected to contain an RDF document in some of the supported RDF formats. PUT
/repositories/<REPOSITORY>/rdf-graphs/<GRAPH> Valid RDF document
Updates data in the named graph in the repository, adding to any existing data in the named graph with the supplied data. The data supplied with this request is expected to contain an RDF document in some of the supported RDF formats. POST
/repositories/<REPOSITORY>/rdf-graphs/<GRAPH> Valid RDF document
Deletes all data in the named graph in the repository. DELETE
/repositories/<REPOSITORY>/rdf-graphs/<GRAPH> -
Fetches statements from the named graph.
GET
/repositories/<REPOSITORY>/rdf-graphs/service
  • graph (optional) - specifies the URI of the named graph to be accessed
  • default (optional) - specifies that the default graph is to be accessed. This parameter is expected to be present but have no value.
    NOTE: Each request needs to specify precisely one of the above parameters.
Updates data in the named graph in the repository, replacing any existing data in the named graph with the supplied data. The data supplied with this request is expected to contain an RDF document in some of the supported RDF formats. PUT
/repositories/<REPOSITORY>/rdf-graphs/service
  • graph (optional) - specifies the URI of the named graph to be accessed
  • default (optional) - specifies that the default graph is to be accessed. This parameter is expected to be present but have no value.
    NOTE: Each request needs to specify precisely one of the above parameters.
Updates data in the named graph in the repository, adding to any existing data in the named graph with the supplied data. The data supplied with this request is expected to contain an RDF document in some of the supported RDF formats. POST
/repositories/<REPOSITORY>/rdf-graphs/service
  • graph (optional) - specifies the URI of the named graph to be accessed
  • default (optional) - specifies that the default graph is to be accessed. This parameter is expected to be present but have no value.
    NOTE: Each request needs to specify precisely one of the above parameters.
Deletes all data in the named graph in the repository. DELETE
/repositories/<REPOSITORY>/rdf-graphs/service
  • graph (optional) - specifies the URI of the named graph to be accessed
  • default (optional) - specifies that the default graph is to be accessed. This parameter is expected to be present but have no value.
    NOTE: Each request needs to specify precisely one of the above parameters.

Working with Namespaces and Contexts

Description Method
URL
Parameters
Gets a list of resources that are used as context identifiers. GET
/repositories/<REPOSITORY>/contexts -
Gets the number of triples in a repository. GET
/repositories/<REPOSITORY>/size
  • context(optional) - If specified,restricts 
    the operation to one or more specific contexts in the repository
Gets a list of namespace declarations that have been defined for the repository. GET
/repositories/<REPOSITORY>/namespaces -
Removes all namespace declarations from the repository. DELETE
/repositories/<REPOSITORY>/namespaces -
Gets the namespace that has been defined for a particular prefix GET /repositories/<REPOSITORY>/namespaces/<PREFIX> -
Defines or updates a namespace declaration, mapping the prefix to the namespace that is supplied in the request body PUT
/repositories/<REPOSITORY>/namespaces/<PREFIX>
  • <NAMESPACE> - plain text - the name of the namespace to be updated
Removes a namespace declaration for a particular prefix DELETE /repositories/<REPOSITORY>/namespaces/<PREFIX> -

Database Configuration

Description
Method
URL
Parameters
Gets the version of the RDF4J (formerly Sesame) server protocol. GET
/protocol  

Content Types

MIME types for RDF formats

Format MIME type
RDF/XML application/rdf+xml
N-Triples text/x-nquads 
Turtle
text/turtle
N3
text/rdf+n3
N-Quads
text/x-nquads
RDF/JSON
application/rdf+json
TriX
application/trix
TriG
application/x-trig
Sesame Binary RDF
application/x-binary-rdf

MIME types for variable binding formats

Format MIME type
SPARQL Query Results XML Format application/sparql-results+xml
SPARQL Query Results JSON Format application/sparql-results+json
Binary RDF Results Table Format
application/x-binary-rdf-results-table

MIME types for boolean result formats

Format MIME type
SPARQL Query Results XML Format application/sparql-results+xml
SPARQL Query Results JSON Format
application/sparql-results+json
Plain Text Boolean Result Format
text/boolean

Sample Code

Sample code is available in the following programming languages:

  • Java
  • C#
  • cURL
  • Python (using urllib2)
  • NodeJS
  • JavaScript
  • Groovy (using HttpBuilder)
  • PHP
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.