Difference between revisions of "OJ Break API Access"
(→Overview) |
(→Overview) |
||
| Line 7: | Line 7: | ||
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. | 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: '''''<nowiki>http://osuc.biosci.ohio-state.edu/ | + | The format for API calls is: '''''<nowiki>http://osuc.biosci.ohio-state.edu/OJ_Break/[method]?[argument1]=[value1]&...</nowiki>''''' |
| − | * Example: '''''<nowiki>http://osuc.biosci.ohio-state.edu/OJ_Break/ | + | * Example: '''''<nowiki>http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonStats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC</nowiki>''''' |
| − | The response for an API call will include a success or error code, | + | 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 | + | * 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. | ||
| + | |||
| + | 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 | ||
| + | |||
| + | === ''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 [[http://osuc-mgr.osu.edu/|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 'Set Up Access' button next to the 'API Key:' text. A unique access key will appear. | ||
Revision as of 16:38, 17 June 2014
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.
Contents
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.
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.
- 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.
- jsonp - Returns the data in the JSON format, but also returns the data to a specific callback argument for procedural calls.
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 [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 'Set Up Access' button next to the 'API Key:' text. A unique access key will appear.
