LinkedDataHub

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 Linked Data Templates specification in combination with the SPARQL 1.1 Graph Store Protocol.

Access control

All HTTP access to documents and graphs 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 (unauthenticated) 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

Method Description Success Failure Reason
GET Returns description of requested resource 200 OK 400 Bad Request Parameter value is invalid
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 (if used with aplt:ForClass parameter)
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
413 Payload Too Large Request body too large
415 Unsupported Media Type Media type not supported
DELETE Removed the description of the requested resource 204 No Content 404 Not Found Resource with request URI not found

Managing graphs

As explained in dataset structure, each document is stored in its own graph. You can navigate from the document to the graph using the void:inDataset property.

Graphs are managed using the SPARQL 1.1 Graph Store HTTP Protocol.

Executing SPARQL

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

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

Hypermedia

In every RDF response that is not a redirect, 201 Created, 404 Not Found you can expect to find an RDF resource with request URI which has argument properties generated from LDT parameters. For example:

@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix ldt:  <https://www.w3.org/ns/ldt#> .
@prefix ldth: <https://www.w3.org/ns/ldt/document-hierarchy/domain#> .
@prefix apl:  <https://w3id.org/atomgraph/linkeddatahub/domain#> .
@prefix spl:  <http://spinrdf.org/spl#> .

<https://linkeddatahub.com/people/?limit=20&desc=true>
    ldt:arg [ a apl:Limit ;
        rdf:value 20 ;
        spl:predicate ldth:limit ;
        ldt:paramName "limit"
    ] ;
    ldt:arg [ a apl:Desc ;
        rdf:value true ;
        spl:predicate ldth:desc ;
        ldt:paramName "desc"
    ] .

Headers

Link headers provide metadata about the matched template, the application base URI and its ontology URI. For example:

Link: <https://linkeddatahub.com/linkeddatahub/docs/>; rel=https://www.w3.org/ns/ldt#base
Link: <https://linkeddatahub.com/linkeddatahub/docs/ns/templates#Document>; rel=https://www.w3.org/ns/ldt#template
Link: <https://linkeddatahub.com/linkeddatahub/docs/ns#>; rel=https://www.w3.org/ns/ldt#ontology

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

Response Cache-Control headers can be controlled using LDT template properties. Responses that are subject to caching, i.e. do not use Authorization header and have a correct Cache-Control value (for example: public, no-transform, max-age=3600) 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).