HTTP API

Learn how to read and write RDF data from/to LinkedDataHub applications over HTTP

LinkedDataHub implements a uniform, generic RESTful Linked Data API as defined by the SPARQL 1.1 Graph Store Protocol. It adds a few conventions and constraints on top of it however.

Authentication

LinkedDataHub UI supports 2 authentication methods:

See how those authentication methods can be configured or how to get an account on LinkedDataHub.

HTTP API access using CLI scripts or curl currently does not support the OIDC method.

Access control

All HTTP access to documents is subject to access control. Requesting a resource with insufficient access rights will result in 403 Forbidden response. That means either:

  • the user is not authenticated and public access to the resource is not allowed
  • the user is authenticated but the associated agent does not have an authorization to perform the action on the requested resource

Managing documents

LinkedDataHub supports the indirect graph identification using the service endpoint and the graph URL parameter as well as the direct identification, since every document is also a named graph.

Method Description Success Failure Reason
GET Returns description of requested resource 200 OK 404 Not Found Resource with request URI not found
406 Not Acceptable Media type not supported
POST Appends data to the application dataset (creates or updates resource descriptions) 200 OK 201 Created 400 Bad Request RDF syntax error
400 Bad Request Constraint violation
409 Conflict Resource already exists
413 Payload Too Large Request body too large
415 Unsupported Media Type Media type not supported
PUT Creates or replaces resource descriptions 200 OK 201 Created 400 Bad Request RDF syntax error
400 Bad Request Constraint violation
400 Bad Request Request body does not contain a document instance
413 Payload Too Large Request body too large
415 Unsupported Media Type Media type not supported
DELETE Removes the description of the requested resource 204 No Content 400 Bad Request Deleting the root document is not allowed
404 Not Found Resource with request URI not found

Graph names

If RDF data is submitted to the service endpoint using the POST method and the graph name is not specified, then the request RDF body must contain one blank node instance of either dh:Item with a sioc:has_container URI value or dh:Container with a sioc:has_parent URI value. They will be used to establish the parent/child relationship of the specified parent container and the document being created from the RDF request body. The new document's URI will be relative to its parent's. For example (Turtle syntax):

@prefix dh:     <https://www.w3.org/ns/ldt/document-hierarchy#> .
@prefix dct:    <http://purl.org/dc/terms/> .
@prefix sioc:   <http://rdfs.org/sioc/ns#> .
@prefix foaf:   <http://xmlns.com/foaf/0.1/> .

[ a dh:Item ;
    sioc:has_container <https://localhost:4443/files/> ;
    dct:title "New file" ;
    foaf:primaryTopic _:file 
] .

# _:file and other resources here

Built-in constraints

LinkedDataHub has a few built-in constraints that are not found in the standard Graph Store Protocol:

  • It's not possible delete the root resource
  • It's not possible to modify or delete the documents of the owner agent and the secretary agent
  • A document (which is also a named graph in the graph store) must always contain an RDF resource with its URI and type def:Root, dh:Container, or dh:Item (see ontologies)

The built in constraints are similar to, but separate from the ontology constraints.

Executing SPARQL

Every LinkedDataHub application provides a SPARQL endpoint on sparql path (relative to the application's base URI). It supports the SPARQL 1.1 Protocol and serves as a proxy for the service endpoint of the application.

System endpoints

Admin and end-user apps

add
Reads data from the specified URL location or uploaded file into the specified named graph
importer
Handles CSV and RDF imports
ns
In-memory namespace ontology as well as its SPARQL endpoint
transform
Reads data from the specified URL location or uploaded file, transforms it using the specified CONSTRUCT query, and stores the result into the specified named graph

Admin app only

admin/request%20accesss
Access request
admin/sign%20up
WebID-TLS agent signup
admin/oauth2/login
OpenID Connect with Google signup
oauth2/authorize/google
OpenID Connect callback
admin/clear
Clears the specified ontology from memory cache and reloads it from the admin SPARQL endpoint

Linked Data proxy

LinkedDataHub works as a Linked Data proxy (from the end-user perspective, as a Linked Data browser) when a URL is provided using the uri query parameter. All HTTP methods are supported.

If the URL dereferences successfully as RDF, LinkedDataHub forwards its response body (re-serializing it to enable content negotiation). During a write request, the request body is forwarded to the provided URL.

The proxy only accepts external (non-relative to the current application's base URI) URLs; local URLs have to be dereferenced directly.

Content negotiation

LinkedDataHub implements proactive conneg based on the request Accept header value. The following RDF media types are supported (for requests as well as responses, unless indicated otherwise):

Error responses

LinkedDataHub provides machine-readable error responses in the requested RDF format. An example of 403 Forbidden:

@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
@prefix http: <http://www.w3.org/2011/http#> .
@prefix sc:   <http://www.w3.org/2011/http-statusCodes#> .
@prefix dct:  <http://purl.org/dc/terms/> .

[ a http:Response ;
    dct:title "Access not authorized" ;
    http:reasonPhrase "Forbidden" ;
    http:sc sc:Forbidden ;
    http:statusCodeValue "403"^^xsd:long
] .

Caching

GET and HEAD RDF responses from the backend triplestores (not LinkedDataHub responses) are cached automatically by LinkedDataHub using Varnish as HTTP proxy cache. You can check the age of the response by inspecting the Age response header (the value is in seconds).

LinkedDataHub sends ETag response headers that are derived as hashes of the requested document's RDF content. Every serialization format (HTML, RDF/XML, Turtle etc.) gets a distinct ETag value.

Caching of LinkedDataHub responses can be enabled on the nginx HTTP proxy server by uncommenting the add_header Cache-Control directives in the platform/nginx.conf.template file. Caching of /uploads/ and /static/ namespaces is enabled by default (since version 4.0.4).