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:

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.

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 document with insufficient access rights will result in 403 Forbidden response. That means either:

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

Managing documents

eEry document is also a named graph in the application's RDF dataset. LinkedDataHub supports the SPARQL Graph Store Protocol's direct graph identification as the HTTP CRUD protocol for managing document data.

GSP indirect graph identification is not supported starting with LinkedDataHub version 5.x.

The API also supports the PATCH HTTP method which is optional in GSP. It accepts graph-scoped SPARQL updates that will modify the requested document. Only the INSERT/WHERE and DELETE WHERE forms are supported; GRAPH patterns are not allowed.

Trailing slashes in document URIs are enforced using 308 Permanent Redirect responses.

Method	Description	Success	Failure	Reason
`GET`	Returns the data of a document	`200 OK`	`404 Not Found`	Document with request URI not found
`GET`	Returns the data of a document	`200 OK`	`406 Not Acceptable`	Media type not supported
`POST`	Appends data to a named graph	`204 No Content`	`400 Bad Request`	RDF syntax error
			`404 Not Found`	Document with request URI not found
			`413 Payload Too Large`	Request body too large
			`415 Unsupported Media Type`	Media type not supported
			`422 Unprocessable Entity`	Constraint violation
`PUT`	Upserts a document	`200 OK` `201 Created` `308 Permanent Redirect`	`400 Bad Request`	RDF syntax error
			`400 Bad Request`	Malformed document URI
			`413 Payload Too Large`	Request body too large
			`415 Unsupported Media Type`	Media type not supported
			`422 Unprocessable Entity`	Constraint violation
`DELETE`	Removes the requested document	`204 No Content`	`400 Bad Request`	Deleting the root document is not allowed
`DELETE`	Removes the requested document	`204 No Content`	`404 Not Found`	Document with request URI not found
`PATCH`	Modifies a document using SPARQL Update	`204 No Content`	`422 Unprocessable Entity`	SPARQL update string violates syntax constraints

Document metadata

Unlike earlier versions, LinkedDataHub 5.x manages the document hierarchy automatically.

By default, LinkedDataHub treats an RDF document as an item by giving it the dh:Item type and attaching it to the parent container using sioc:has_container. If the client wants to create a container instead, it has to explicitly add the dh:Container type on the document resource; the new container will be attached to its parent using sioc:has_container. In either case, the URI of the new document's will be relative to its parent's.

LinkedDataHub will also manage additional document metadata, such as its owner and creation/modification timestamps.

For example, this HTTP request to create a new container (Turtle syntax):

PUT /namedgraph/new-container/ HTTP/1.1
Host: linkeddatahub.com
Content-Type: text/turtle

@prefix dh:     <https://www.w3.org/ns/ldt/document-hierarchy#> .
@prefix dct:    <http://purl.org/dc/terms/> .

<> a dh:Container ;
    dct:title "New container" .

will produce the following document triples:

@prefix dh:     <https://www.w3.org/ns/ldt/document-hierarchy#> .
@prefix dct:    <http://purl.org/dc/terms/> .
@prefix xsd:    <http://www.w3.org/2001/XMLSchema#> .
@prefix sioc:   <http://rdfs.org/sioc/ns#> .
@prefix acl:    <http://www.w3.org/ns/auth/acl#> .

<https://linkeddatahub.com/namedgraph/new-container/>
    a dh:Container ;
    dct:created "2025-03-31T21:46:21.984Z"^^xsd:dateTime ;
    dct:creator <https://linkeddatahub.com/namedgraph/admin/acl/agents/fda0009e-191b-4f07-838c-5daf2a74b35f/#this> ;
    dct:title "New container" ;
    sioc:has_parent <https://linkeddatahub.com/namedgraph/> ;
    acl:owner <https://linkeddatahub.com/namedgraph/admin/acl/agents/fda0009e-191b-4f07-838c-5daf2a74b35f/#this> .

The HTTP request to produce a new item can be empty:

PUT /namedgraph/new-container/ HTTP/1.1
Host: linkeddatahub.com
Content-Type: text/turtle

It will create an item document with the following triples:

@prefix dh:    <https://www.w3.org/ns/ldt/document-hierarchy#> .
@prefix dct:    <http://purl.org/dc/terms/> .
@prefix xsd:    <http://www.w3.org/2001/XMLSchema#> .
@prefix sioc:   <http://rdfs.org/sioc/ns#> .
@prefix acl:    <http://www.w3.org/ns/auth/acl#> .

<https://linkeddatahub.com/namedgraph/new-item/>
    a dh:Item ;
    dct:created "2025-03-31T20:45:42.802Z"^^xsd:dateTime ;
    dct:creator <https://linkeddatahub.com/acl/agents/d47e1f9b-c8d0-4546-840f-5d9fbb479da2/#id9d3814f2-53bc-42e9-b1ab-46cbc9a94263> ;
    sioc:has_container <https://linkeddatahub.com/namedgraph/> ;
    acl:owner <https://linkeddatahub.com/admin/acl/agents/d47e1f9b-c8d0-4546-840f-5d9fbb479da2/#id9d3814f2-53bc-42e9-b1ab-46cbc9a94263> .

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 document
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/access: Access metadata (for the authenticated agent)
admin/access/request: Access request (for the authenticated agent)
admin/sign%20up: WebID-WebID agent signup
admin/oauth2/login: OpenID Connect with Google signup
admin/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).