HTTP API

Authentication

LinkedDataHub UI supports 2 authentication methods:

• WebID-TLS using TLS client certificates
• OpenID Connect using Google

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

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.

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):

• Turtle text/turtle
• N-Triples application/n-triples
• RDF/XML application/rdf+xml
• JSON-LD application/ld+json
• RDF/POST application/x-www-form-urlencoded (for requests only)

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).