Overview

The Data Distribution API is used to create data feeds from your VIVO site by editing a configuration file.

Use data feeds to:

• provide content to other sites
• service AJAX requests from your own VIVO pages
• provide a more responsive user interface on your VIVO site
• drive visualizations of your VIVO data

Get more use of the data in your VIVO site

• without opening your site to expensive queries
• without digging into the internals of VIVO
• without writing any Java code

You will likely need to know SPARQL, Turtle syntax for RDF, and the structure of your data in VIVO.

For more on the motivation and design philosophy behind the Data Distribution API, see Data Distribution motivation

Hello, World

As a first example, we create an API that can be called to return the text "Hello, World" – not very useful, but shows the basic mechanism for creating and using an API based on a configuration file.  

First, create a Turtle format file in <vivo-home>/rdf/display/everytime You may name the file anything you like.  All example files are in Turtle format.  Turtle files typically have a .ttl file type.  Your file should contain the following:

@prefix : <http://vitro.mannlib.cornell.edu/ns/vitro/ApplicationSetup#> .
  
:data_distributor_hello
    a   <java:edu.cornell.library.scholars.webapp.controller.api.distribute.DataDistributor> ,
        <java:edu.cornell.library.scholars.webapp.controller.api.distribute.examples.HelloDistributor> ;
    :actionName "hello" .

Second, restart Tomcat.  VIVO will reread its everytime content.  The assertions in the Turtle file will be added to VIVO's content triple store.  The API is now ready for use.

Third, visit the URL:  http://mydomain.edu/api/datarequest/hello

You should see:

Hello, World

in your browser.

Parameters

The HelloDistributor supports a name parameter which can be specified in the call:

Visit http://mydomain.edu/api/datarequest/hello?name=Bob

You should see:

Hello, Bob

in your browser.

The Data Distribution API supports parameterized requests, making it ideal for getting data about a particular person, a particular publication, all the people in a particular department, and so on.

How to Read the Configuration File

The configuration file begins with a prefix. Prefixes provide shortcuts for URIs used in RDF.  See the Turtle reference for additional background and examples.

Following are two assertions of type for a new entity with the URI :data_distributor_hello.  You can use any URI for your data distributor entity.  You will need to use unique URI for each data distributor entity you create, so a naming convention (see below) may be helpful.

The type assertions are required and declare that the entity is a data distributor, and is a HelloDistributor.  Subsequent examples will use other types of data distributors.

The third assertion says that the entity has the actionName "hello".  This is the API's key for someone calling the API.  The entity will be called when the URL http://mydomain.edu/api/datarequest/hello is visited.  The "/api/datarequest" part of the URL is fixed and indicates you are making a request of the VIVO Data Distribution API.  The final part of the URL is the action name specified in the configuration file.

Managing Configuration Files

Your configuration files will live in <vivo-home>/rdf/display/everytime

You may wish to use a naming convention to identify Data Distribution API configuration files.

You will want to preserve your configuration files through upgrades and builds of VIVO.  See Preserving Customizations During Build

References

1. VIVO Data Distribution API on GitHub https://vivo-community.github.io/vivo-data-distribution-api/

2. Turtle - Terse RDF Triple Language https://www.w3.org/TeamSubmission/turtle/

3. Learning SPARQL http://learningsparql.com 

4. VIVO Ontology Reference