HTTP API

CRUD operations

This table shows a mapping between URIs, HTTP methods and operations.

Template	GET	POST	PUT	DELETE
dht:Container	List	Create
dht:Item	Read		Update	Delete

The update is done using SPARQL 1.1 Update command defined by the LDT template's ldt:update property. However, Graph Store Protocol is often more convenient .

Content negotiation is implemented via the Accept request header.

Here's the map of AtomGraph Processor HTTP API:

Method	Request payload	Target class	Provenance	SPARQL operation	Target graph	Response status
POST	dh:Container	dh:Container	every foaf:Document gets sioc:has_container <target>	INSERT DATA	default	303 See Other if success 400 Bad Request if constraint validation
	dh:Document		every dh:Container gets sioc:has_parent <target>
PUT	dh:Document	dh:Document		DELETE using dh:update INSERT DATA	default	200 OK if success 400 Bad Request if constraint validation
		none	???	INSERT DATA		201 Created
DELETE		dh:Container		DELETE using dh:update	default	204 No Content
		dh:Document

All RDF serializations supported by Jena (registered in RDFLanguages) are accepted.

Validation

All incoming RDF is validated using SPIN API against the spin:constraints in the sitemap. If any constraint is violated, the request is rejected and response with 400 Bad Request status is returned.

The constraints themselves are either ASK (for a simple true/false answer) or CONSTRUCT (for a more detailed violation message) queries. The Data Quality Constraints Library is a useful ontology to import, as it contains some often needed constraints such as a check for missing properties.

Consider the following resource class with a constraint (other properties omitted):

@prefix owl:	<http://www.w3.org/2002/07/owl#> .
@prefix sp:     <http://spinrdf.org/sp#> .
@prefix spin:	<http://spinrdf.org/spin#> .
@prefix dqc:	<http://semwebquality.org/ontologies/dq-constraints#> .

dh:Document a owl:Class ;
    spin:constraint [ a dqc:MissingProperties ;
	    sp:arg1 dh:Document ;
	    sp:arg2 dh:slug
	] .

and the following POST request body:

@prefix dh:	<https://www.w3.org/ns/ldt/document-hierarchy/domain#> .

_:item a dh:Document .

The request will be rejected, as the _:item resource has dh:Document type but does not have the dh:slug property required by the SPIN constraint.

Skolemization

Blank nodes in POST request payload are skolemized, i.e. renamed into URI resources. URI template is defined for a class using ldt:path, which allows to use resource property values in the URI and navigating to related resource descriptions using a property path-like syntax.

Resources that are do not have foaf:Document type (e.g. denoting physical object such as foaf:Person instance or abstract concept such as skos:Concept terms) should have have different URIs from the documents that are describing them. One simple convention for doing that is to use fragment URIs for them, e.g. by adding #this fragment to the document URI. Another LDT property ldt:fragment can be used to specify that for a class.

After a relative URI is built from the template, it is resolved against the request URI and becomes absolute. Only resources with recognized type classes are skolemized, unmatched bnodes are left untouched.

For example, using http://localhost:8080/Web-Client/items/ as POST request URI, skolemizing the following request body

@prefix dh:	<https://www.w3.org/ns/ldt/document-hierarchy/domain#> .
@prefix foaf:   <http://xmlns.com/foaf/0.1/> .

_:item a dh:Document ;
  foaf:primaryTopic _:thing .
_:thing a a owl:Thing ;
  rdfs:label "I'm a Thing" ;
  foaf:isPrimaryTopicOf _:item .

while processing a LDT ontology with the following triples

dh:Document ldt:path "{primaryTopic.label}" . # fake property path, using local names only` 
owl:Thing ldt:path "{label}" .

yields following result which is ready to be stored in the triplestore:

@prefix dh:	<https://www.w3.org/ns/ldt/document-hierarchy/domain#> .
@prefix foaf:   <http://xmlns.com/foaf/0.1/> .

<http://localhost:8080/Web-Client/items/I%27m%20a%20Thing> a dh:Document ;
  foaf:primaryTopic <http://localhost:8080/Web-Client/items/I%27m%20a%20Thing#this> .
<http://localhost:8080/Web-Client/items/I%27m%20a%20Thing#this> a owl:Thing ;
  foaf:isPrimaryTopicOf <http://localhost:8080/Web-Client/items/I%27m%20a%20Thing> .