...
Panel |
---|
Excerpt |
---|
Remote applications can perform SPARQL Update calls to add RDF to VIVO, or to remove existing RDF. Since VIVO 1.6. |
|
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.
...
The API supports only HTTP POST calls. GET, HEAD, and other methods are not supported, and will return a response code of 400 Bad Request
405 Method Not Allowed
.
Parameters
name | value |
---|
email | the email address of a VIVO adminstrator account |
password | the password of the VIVO administrator account |
update | A SPARQL Update request |
...
Code | Reason |
---|
200 OK | SPARQL Update was successful. |
400 Bad Request | Incorrect HTTP method; only POST is accepted.HTTP request did not include an update parameter. |
The SPARQL Update request did not specify a GRAPH on which to operate. |
The SPARQL Update request was syntactically incorrect. |
403 Forbidden | HTTP request did not include an email parameter. |
HTTP request did not include a password parameter. |
The combination of email and password is not valid. |
The selected VIVO account is not authorized to use the SPARQL Update API. |
405 Method Not Allowed | Incorrect HTTP method; only POST is accepted. |
500 Internal Server Error | VIVO could not execute the request; internal code threw an exception. |
...
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.
Code Block |
---|
|
curl -i -d 'email=testAdmin@mydomain.edu' -d 'password=Password' -d '@insert.sparql' 'http://localhost:8080/vivo/api/sparqlUpdate' |
Code Block |
---|
|
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.
Code Block |
---|
|
curl -i -d 'email=testAdmin@mydomain.edu' -d 'password=Password' -d '@modify.sparql' 'http://localhost:8080/vivo/api/sparqlUpdate' |
Code Block |
---|
|
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.
Code Block |
---|
|
curl -i -d 'email=testAdmin@mydomain.edu' -d 'password=Password' -d '@delete.sparql' 'http://localhost:8080/vivo/api/sparqlUpdate' |
Code Block |
---|
|
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" .
}
} |
A more complex deletion
This update removes an Email address from a Person in VIVO. The Person is related to a VCard:ContactInfo object, which is related to a VCard:EMail object, which has the email address in a data property.
Code Block |
---|
|
curl -i -d 'email=testAdmin@mydomain.edu' -d 'password=Password' -d '@delete_email.ru' 'http://localhost:8080/vivo/api/sparqlUpdate' |
Code Block |
---|
|
update=
PREFIX obo: <http://purl.obolibrary.org/obo/>
PREFIX vcard: <http://www.w3.org/2006/vcard/ns#>
DELETE {
GRAPH <http://vitro.mannlib.cornell.edu/default/vitro-kb-2> {
?contactInfo vcard:hasEmail ?emailObject .
?emailObject ?p1 ?o .
}
} WHERE {
GRAPH <http://vitro.mannlib.cornell.edu/default/vitro-kb-2> {
<http://vivo.mydomain.edu/individual/n4295> obo:ARG_2000028 ?contactInfo .
?contactInfo vcard:hasEmail ?emailObject .
?emailObject vcard:email "my.primary@email.com"^^<http://www.w3.org/2001/XMLSchema#string> .
?emailObject ?p1 ?o .
}
} |
Big Files
For big 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 make it accessible at a URL that VIVO can access. In the example below, the RDF file containing the triples are the data.rdf (available in the root directory of the web server that respond by the address myserver.address.xxx) and the sparql file below contains the LOAD command to be execute by the SPARQL VIVO API.
Code Block |
---|
language | xml |
---|
title | import.sparql |
---|
linenumbers | true |
---|
|
update=LOAD <http://myserver.address.xxx/data.rdf> into graph <http://vitro.mannlib.cornell.edu/default/vitro-kb-2> |
The command should be the same used in the last examples where USER is a user email authorized to access the SPARQL API (see below) or the email of the root user (created during the install process). The PASSWORD.
Code Block |
---|
language | bash |
---|
title | command |
---|
linenumbers | true |
---|
|
curl -d 'email=USER' -d 'password=PASSWORD' -d '@import.sparql' 'http://localhost:8080/vivo/api/sparqlUpdate' |
A Python example
Ted Lawless of Brown University has created a Python program to illustrate the SPARQL Update API. You can find it here: https://gist.github.com/lawlesst/6300573#file-vupdate-py
Enabling the API
Note |
---|
Before enabling the SPARQL update handler, you should secure the URL api/sparqlUpdate with HTTPS. Otherwise, email/password combinations will be sent across the network without encryption. Methods for securing the URL will depend on your site's configuration. |
...
Code Block |
---|
title | authorizeSparqlUpdate.n3 |
---|
|
@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 .
. |
Comment: Actually, this is not 100% true. The root user can always use the SPARQL API and the file [vivo]/rdf/auth/everytime/permission_config.n3
already contains the line above commented. One only need to uncomment this line to enable the API.