RESTful data access

Wildbook allows other computer programs to push and pull data to and from it through a REspresentational State Transfer (REST) data interface with JavaScript Object Notation (JSON) data. Why is this important? This interface allows your team to build your own, separate applications that push data to Wildbook or pull data from it. For example, you might give a biostatistician access to your Wildbook's REST interface so that they can do custom population modeling in R using your data, pulling the latest data with every run. In another example, you might provide access to your Wildbook's REST interface to a computer vision specialist developing a new, automated individual identification system for your species, ensuring that the specialist always has predictable access to the latest data from your study.

Having a RESTful data interface means that Wildbook can be one of many programs working together to manage and analyze data in your study.

The principles of REST are well documented on the web, such as in this article: http://en.wikipedia.org/wiki/Representational_state_transfer

The programming-language independent method of displaying data called JSON is also well documented elsewhere, such as in this article: http://en.wikipedia.org/wiki/JSON

Wildbook's REST interface by default uses the base URL of:

http:<your_project_URL>/<your_wildbook_version>/rest

For example, if properly configured, your Wildbook will list all of the Encounters submitted within it as a list of JSON objects displayed at the URL:

http:<your_project_URL>/<your_wildbook_version>/rest/org.ecocean.Encounter

Here is a real world example from the Wildbook demo site: http://www.splashcatalog.org/mmuwildbook/rest/demo/org.ecocean.Encounter

Here are examples of accessing RESTful data in Wildbook.

http://www.splashcatalog.org/mmuwildbook/rest/demo/org.ecocean.MarkedIndividual/410001

which corresponds to this page in Wildbook:

http://www.splashcatalog.org/mmuwildbook/individuals.jsp?number=410001&context=context6

Here is how you could get the data for Encounter 462 from Wildbook's REST interface in the JSON data format:

http://www.splashcatalog.org/mmuwildbook/rest/demo/org.ecocean.Encounter/562

Here is how you could get the metadata for the SinglePhotoVideo objects (its uploaded media) for Encounter 462 from Wildbook's REST interface in the JSON data format:

http://www.splashcatalog.org/mmuwildbook/rest/demo/org.ecocean.SinglePhotoVideo?correspondingEncounterNumber=="562"

While REST support allows your wildbook to work with other research applications in your project, it also means that your data is potentially exposed for others to easily take. By default, Wildbook protects the REST URL with this configuration in web.xml:

/rest/** = authcBasicWildbook,roles[rest]

This configuration means two things:

1. A user attempting to access the REST URL must be authenticated using HTTP BASIC if not already authenticated.
2. The user that authenticates to the URL must have the “rest” role.

This means that by default your data is protected. To provide another application with access, two things must happen.

1. You must create a user account in Wildbook and assign it only the “rest” role. This means that the application can access the REST interface but that its credentials cannot be used to log into the user interface of Wildbook.
2. The application must authenticate to the REST interface with HTTP BASIC credentials in the URL. For example:

http://<username>:<password>@<your_wildbook_url>/rest/org.ecocean.Encounter

Wildbook uses the Apache Shiro open source project for security. To learn more about Apache Shiro and how you might further modify web.xml for your own customer REST interface, check out this resource:

http://shiro.apache.org/web.html

Within Wildbook, data storage is managed by the open source DataNucleus project, which provides the functionality that allows WIldbook to store data in multiple database types. DataNucleus provides the REST data interface used by Wildbook, and more information about it can be found here:

http://www.datanucleus.org/products/accessplatform/rest/api.html