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.


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:     <> .
@prefix dct:    <> .
@prefix sioc:   <> .
@prefix foaf:   <> .

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

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:  <> .
@prefix http: <> .
@prefix sc:   <> .
@prefix dct:  <> .

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


GET and HEAD responses will be 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).