Purpose

Permits external applications to add or remove specific triples from the VIVO data model. These changes use the standard data channels in VIVO, so the search index will be updated as appropriate, and the reasoner will add or remove inferences as needed.

Use Cases

Harvester

Previous implementations of the Harvester and similar tools have written directly to the VIVO triple-store, bypassing the usual data channels in VIVO. After ingesting, it was necessary to rebuild the search index, and to run the reasoner to add or remove inferences. Since the search index and the reasoner were not aware of the exact changes, the entire data model was re-indexed and re-inferenced.

When the Harvester and other tools have been modified to use the SPARQL Update API, VIVO will ensure that the search index and inferences are kept in synchronization with the data.

Other ingest tools

This API permits ingest tools such as Karma to programmatically insert data into VIVO without requiring knowledge of VIVOs internal data structures.

VIVO "face" applications

Linked Open Data requests have permitted people to write Drupal applications (for example) that display data from VIVO. This API will permit such applications to accept user edits, and apply them back to VIVO.

Specification

URL

[vivo]/api/sparqlUpdate

Examples:

http://vivo.cornell.edu/api/sparqlUpdate

http://localhost:8080/vivo/api/sparqlUpdate

HTTP Method

The API supports only HTTP POST calls. GET, HEAD, and other methods are not supported, and will return a response code of 405 Method Not Allowed.

Parameters

The syntax for a SPARQL Update request is described on the World Wide Web Consortium site at http://www.w3.org/TR/2013/REC-sparql11-update-20130321/

Limitation

The API requires that you specify a GRAPH in your SPARQL update request. Insertions or deletions to the default graph are not supported.

Response Codes

Examples

These examples use the UNIX curl command to insert and delete data using the API.

Insert example

This example inserts a single RDF statement into the data model.

curl -i -d 'email=testAdmin@mydomain.edu' -d 'password=Password' -d '@insert.sparql' 'http://localhost:8080/vivo/api/sparqlUpdate'

update=INSERT DATA { 
   GRAPH <http://vitro.mannlib.cornell.edu/default/vitro-kb-2> { 
      <http://test.domain/ns#book1> 
          <http://purl.org/dc/elements/1.1/title> 
          "Fundamentals of Compiler Design" . 
    } 
}

Modify example

This example removes the previous statement, and inserts a replacement.

curl -i -d 'email=testAdmin@mydomain.edu' -d 'password=Password' -d '@modify.sparql' 'http://localhost:8080/vivo/api/sparqlUpdate'

update=DELETE DATA { 
   GRAPH <http://vitro.mannlib.cornell.edu/default/vitro-kb-2> { 
      <http://test.domain/ns#book1> 
          <http://purl.org/dc/elements/1.1/title> 
          "Fundamentals of Compiler Design" . 
    } 
}
INSERT DATA { 
   GRAPH <http://vitro.mannlib.cornell.edu/default/vitro-kb-2> { 
      <http://test.domain/ns#book1> 
          <http://purl.org/dc/elements/1.1/title> 
          "Design Patterns" . 
    } 
}

Delete example

This example removes the modified statement.

 curl -i -d 'email=testAdmin@mydomain.edu' -d 'password=Password' -d '@delete.sparql' 'http://localhost:8080/vivo/api/sparqlUpdate'

update=DELETE DATA { 
   GRAPH <http://vitro.mannlib.cornell.edu/default/vitro-kb-2> { 
      <http://test.domain/ns#book1> 
          <http://purl.org/dc/elements/1.1/title> 
          "Design Patterns" . 
    } 
}

Large Files

For large files one can also use the SPARQL LOAD command.

For this, you have to first create the RDF file with the triples that you want to add, and make the file accessible at a URL. In the example below, the RDF file containing the triples is called data.rdf, and is available in the root directory of the web server at myserver.address.xxx.

Like the previous commands, this one references a data file, in this case called import.sparql. That file contains the LOAD command which references the actual data.

curl -d 'email=USER' -d 'password=PASSWORD' -d '@import.sparql' 'http://localhost:8080/vivo/api/sparqlUpdate'

update=LOAD <http://myserver.address.xxx/data.rdf> into graph <http://vitro.mannlib.cornell.edu/default/vitro-kb-2>

Increase the default Tomcat maxPostSize

By default, Tomcat sets the default maximum of a POST request to 2 megabytes. If you want to increase this to be able to POST larger sets of triples to VIVO, you can use the maxPostSize attribute in server.xml. The example below would increase the maximum to 10 MB. See the Tomcat documentation for more details.

<Connector port="8080" protocol="HTTP/1.1"
    connectionTimeout="20000"
   URIEncoding="UTF-8"
   redirectPort="8443" 
   maxPostSize="10485760"/>

Enabling the API

By default, the SPARQL Update handler is enabled for only the root user in VIVO. To enable it for other user groups, you can either:

•   uncomment the line references "UseSparqUpdateAPI" in [vitro]/rdf/auth/everytime/permission_config.n3 or
•   create an RDF file in the [vitro]/rdf/auth/everytime directory that will authorize your site administrators to use the API. Below is an example of such a file, using N3 syntax.

@prefix auth: <http://vitro.mannlib.cornell.edu/ns/vitro/authorization#> .
@prefix simplePermission: <java:edu.cornell.mannlib.vitro.webapp.auth.permissions.SimplePermission#> .
 
# Authorize the ADMIN role to use the SPARQL Update API
auth:ADMIN auth:hasPermission simplePermission:UseSparqlUpdateApi .