HTTP API

CRUD operations

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

Method	Success	Failure	Message
GET	200 OK		Resource description returned
		400 Bad Request	Unrecognized parameter name
		400 Bad Request	Invalid parameter value
		404 Not Found	Resource not found
		406 Not Acceptable	Media type not supported
POST	200 OK		Dataset appended
		400 Bad Request	Invalid request body syntax
		400 Bad Request	Constraint violation
		404 Not Found	Resource not found
		409 Conflict	Resource already exists
		415 Unsupported Media Type	Media type not supported
PUT	200 OK		Resource description updated
		400 Bad Request	Invalid request body syntax
		400 Bad Request	Constraint violation
		404 Not Found	Resource not found
		409 Conflict	Resource description has changed
		415 Unsupported Media Type	Media type not supported
DELETE	204 No Content		Resource deleted
		404 Not Found	Resource not found

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. All RDF serializations supported by Jena (registered in RDFLanguages) are accepted. A streaming RDF/POST reader is registered as well.

Validation

All incoming RDF is validated using SPIN API against the spin:constraints in the domain ontology. 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/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}" . # 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/items/I%27m%20a%20Thing> a dh:Document ;
  foaf:primaryTopic <http://localhost:8080/items/I%27m%20a%20Thing#this> .
<http://localhost:8080/items/I%27m%20a%20Thing#this> a owl:Thing ;
  foaf:isPrimaryTopicOf <http://localhost:8080/items/I%27m%20a%20Thing> .