OJ Break API Access

Introduction

OJ_Break is the name of the xBio:D RESTful(-like) API service to facilitate discovery of data within the xBio:D database. The API responds exclusively in JavaScript Object Notation (JSON) and accepts only HTTP GET and POST requests indiscriminately unlike a true REST API. Built using Oracle's PL/SQL database language, the API is fast but often inflexible and inconsistent, so take note of all of the comments below.

Overview

All API requests must be formatted by first selecting the OJ_Break library then specifying the API method. Also, each method must include a format and key argument.

The format for API calls is: http://osuc.biosci.ohio-state.edu/OJ_Break/[method]?[argument1]=[value1]&...

• Example: http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonStats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

The response for an API call will include a success or error code, a corresponding response message, and the included data returned by the method call displayed according to the value of the format parameter.

• Response: {"code":100,"message":"API resource successfully retrieved","data":{"taxon":"Heptascelio striatosternus","author":"Narendran & Ramesh Babu","stats":...

Arguments

Method Specific Parameters

When calling a method, the corresponding parameters necessary must be included and have valid values. All methods and their parameters are included in the OJ_Break API Help page. In the example below, the method getTaxonStats needs the parameter tnuid to return the correct data.

   Example: http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonStats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

format

The format parameter specifies the structure of the data being recieved by an API call. The value for the parameter can be either json, jsonp, or xml.

• json - JavaScript Object Notation is a lightweight data-interchange format made up of objects and arrays. Arrays can hold many elements of one data type, and objects can hold keys with associated values of many data types.

   Example: http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonHierarchy?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

• xml - Extensible Markup Language is a hierarchy based data-structure that is easy to read by humans. The language is made up of tags, similar to HTML, to display data. Instead of data types, the xml parameter assigns each tag a type attribute that signifies the type of the tag value.

   Example: http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonHierarchy?tnuid=30148&format=xml&key=FBF57A9F7A666FC0E0430100007F0CDC

• jsonp - Returns the data in the JSON format, but also returns the data to a specific callback argument for procedural calls.

   Example: http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonStats?tnuid=30148&callback=api&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC

callback

The callback parameter is only necessary when format is specified as jsonp. This gives a procedural call to the value given by callback with the data retrieved.

   Example: http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonStats?tnuid=30148&callback=test&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC

key

The key parameter is a Database Manager defined API access code. The given key is for testing and example purposes.

Getting a Key

To get an API access key, go to the OJ_Break Database Manager website and sign in with a valid username and password.

On the left side of the screen, click on Manage API Access.

Finally, click the Set Up Access button next to the 'API Key:' text. A unique access key will appear.