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 theSPARQL 1.1 Graph Store Protocol. It adds a fewconventions andconstraints 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 beconfigured or how toget an account on LinkedDataHub.
HTTP API access usingCLI scripts or curl currently does not support the OIDC method.
Access control
All HTTP access todocuments is subject toaccess control. Requesting a document with insufficient access rights will result in403 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 toperform the action on the requested document
Managing documents
Every document is also anamed graph in the application's RDF dataset. LinkedDataHub supports the SPARQL Graph Store Protocol'sdirect graph identification as the HTTP CRUD protocol for managing document data.
GSPindirect graph identification is not supported starting with LinkedDataHub version 5.x.
The API also supports thePATCH HTTP method which isoptional in GSP. It accepts graph-scoped SPARQL updates that will modify the requested document. Only theINSERT/WHERE andDELETE WHERE forms are supported;GRAPH patterns are not allowed.
Trailing slashes in document URIs are enforced using308 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 |
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 OK201 Created308 Permanent Redirect | 400 Bad Request | RDF syntax error |
| 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 |
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 thedocument hierarchy automatically.
By default, LinkedDataHub treats an RDF document as an item by giving it thedh:Item type and attaching it to the parent container usingsioc:has_container. If the client wants to create a container instead, it has to explicitly add thedh:Container type on the document resource; the new container will be attached to its parent usingsioc: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.1Host: linkeddatahub.comContent-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.1Host: linkeddatahub.comContent-Type: text/turtleIt 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 can only be created with a URL relative to an existing container (i.e. resolving.. against the new document's URL must identify an existing container)
The built in constraints are similar to, but separate from theontology constraints.
Executing SPARQL
Every LinkedDataHub application provides a SPARQL endpoint onsparql path (relative to the application's base URI). It supports theSPARQL 1.1 Protocol and serves as a proxy for the backend 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
CONSTRUCTquery, 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 aLinked Data proxy (from the end-user perspective, as aLinked Data browser) when a URL is provided using theuri 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 implementsproactive conneg based on the requestAccept 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 of403 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 andHEAD RDF responses from the backend triplestores (not LinkedDataHub responses) are cached automatically by LinkedDataHub usingVarnish as HTTP proxy cache. You can check the age of the response by inspecting theAge response header (the value is in seconds).
LinkedDataHub sendsETag response headers that are derived as hashes of the requested document's RDF content. Every serialization format (HTML, RDF/XML, Turtle etc.) gets a distinctETag value.
Caching of LinkedDataHub responses can be enabled on the nginx HTTP proxy server by uncommenting theadd_header Cache-Control directives in theplatform/nginx.conf.template file. Caching of/uploads/ and/static/ namespaces is enabled by default (since version 4.0.4).