Difference between revisions of "OJ Break API Access"

From xBio:D Wiki
Jump to navigation Jump to search
(→‎Overview)
(→‎Arguments)
 
(40 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
'''Introduction'''
 
'''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.
+
In order to access the OJ_Break API, follow the instructions below. An API key linked to an xBio:D user account is required to use the API.
  
  
 
== Overview ==
 
== 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.
+
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'', ''key'', and ''version'' argument.
−
 
+
The format for API calls is: '''''<nowiki>http://xbiod.osu.edu/OJ_Break/[method]?[argument1]=[value1]&...</nowiki>'''''
−
The format for API calls is: '''''<nowiki>http://osuc.biosci.ohio-state.edu/OJ_Break/[method]?[argument1]=[value1]&...</nowiki>'''''
+
    Example: '''''<nowiki>http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2</nowiki>'''''
−
* 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, a corresponding response message, and the included data returned by the method call displayed according to the value of the ''format'' parameter.
 
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":...'''''
+
    Response: '''''{"code":100,"message":"API resource successfully retrieved","data":{"taxon":"Heptascelio striatosternus","author":"Narendran & Ramesh Babu","stats":...'''''
  
 
== Arguments ==
 
== Arguments ==
 
=== Method Specific Parameters ===
 
=== 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.
+
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 [[OJ Break API Help#getTaxonStats|getTaxonStats]] needs the parameter [[OJ Break API Data Type Glossary#tnuid_2|tnuid]] to return the desired data.
  
−
Example: http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonStats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC
+
    Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2
  
 
=== ''format'' ===  
 
=== ''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'''.
+
The ''format'' parameter specifies the structure of the data being received by an API call. The value for the parameter can be either '''json''' (default), '''jsonp''', '''html''', 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.  
+
*'''''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
+
    Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2
  
−
* '''''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.
+
* '''''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
+
    Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=xml&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2
  
−
* '''''jsonp''''' - Returns the data in the JSON format, but also returns the data to a specific callback argument for procedural calls.
+
* '''''html''''': Hypertext Markup Language is the foundational language for the world wide web. Since web browsers are designed to interpret and display HTML, this is the most human-readable format and should generally not be used for machine-to-machine transactions.
−
Example: http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonStats?tnuid=30148&callback=api&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC
+
    Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2
 +
 
 +
* '''''jsonp''''': JavaScript Object Notation with Padding returns the data in the JSON format but wrapped within a specified '''callback''' argument for procedural calls.
 +
    Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&callback=api&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2
 +
 
 +
=== ''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://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&callback=test&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2
  
 
=== ''key'' ===
 
=== ''key'' ===
−
The ''key'' parameter is a Database Manager defined API access code. The given key is for testing and example purposes.
+
The ''key'' parameter is a Database Manager defined API access code. The key used in the OJ_Break API reference is for testing and example purposes only.
  
 
==== Getting a Key ====
 
==== 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.  
+
To get an API access key, go to the [http://osuc-mgr.osu.edu/ Database Manager website] and sign up or sign in with a valid username and password.  
 +
 
 +
[[File:API_Access_tut_login.png|frame|none|Shown are the username and passwords fields to sign into Database Manager. If an account needs to be created, clicking the sign up button redirects to an account creation page.|link=http://osuc-mgr.osu.edu/]]
 +
 
  
 
On the left side of the screen, click on '''Manage API Access'''.  
 
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.
+
[[File:API_Access_tut_manage.png|frame|none|The Manage API Access link is shown. This link will bring up the API Access page.|link=http://osuc-mgr.osu.edu/]]
 +
 
 +
 
 +
Finally, click the '''Set Up Access''' button next to the 'API Key:' text. A unique access key will appear.
 +
 
 +
[[File:API_Access_tut2.png|frame|none|Shown here is the API Key button on the API Access page. Clicking the Set Up Access button will reveal a unique database key.|link=http://osuc-mgr.osu.edu/]]
 +
 
 +
== Responses ==
 +
Every call to the API, regardless of the format, will return three main articles of information: ''code'', ''message'', and ''data''.
 +
 
 +
Roughly, the arrangement of the response will be similar to:
 +
'''code:[''code''], message:[''code message''], data:[''method return'']'''
 +
=== ''code'' ===
 +
[[File:API_Access_tut_error.png|alt=A popup containing an error message stating that access is denied to the API.|frame|none|An example of an error alert. Error code 901 is shown to help describe possible causes.]]
 +
 
 +
The ''code'' key/tag contains a three digit number whose value depends on the state of the API request. Below is a list of all possible codes and their significance.
 +
* '''100''': Success
 +
* '''900''': Error
 +
* '''901''': Error
 +
* '''902''': Error
 +
* '''903''': Error
 +
 
 +
=== ''message'' ===
 +
 
 +
The ''message'' response will accompany the received ''code'' number as an explanation for the state of the API request. Below is a list of the possible codes and their cooresponding messages.
 +
 
 +
* ''code'' '''100''': ''message'': '''"API resource successfully retrieved"'''
 +
* ''code'' '''900''': ''message'': '''"API resource not specified"'''
 +
* ''code'' '''901''': ''message'': '''"API resource could not complete request (reasons: resource not available, parameters missing, malformed parameter value, or internal system error)"'''
 +
* ''code'' '''902''': ''message'': '''"API key is either missing or invalid"'''
 +
* ''code'' '''903''': ''message'': '''"Server is not authorized to use the API for the specified API key"'''
 +
 
 +
=== ''data'' ===
 +
All of the returned information from the API call will be found organized in the ''data'' key/tag. This information will only be present with a successful API retrieval.
 +
 
 +
 
 +
[[Category:OJ_Break API]]

Latest revision as of 20:51, 22 April 2015

Introduction

In order to access the OJ_Break API, follow the instructions below. An API key linked to an xBio:D user account is required to use the API.


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, key, and version argument. The format for API calls is: http://xbiod.osu.edu/OJ_Break/[method]?[argument1]=[value1]&... 

   Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

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 desired data. 

   Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

format

The format parameter specifies the structure of the data being received by an API call. The value for the parameter can be either json (default), jsonp, html, 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://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2
  • 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://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=xml&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2
  • html: Hypertext Markup Language is the foundational language for the world wide web. Since web browsers are designed to interpret and display HTML, this is the most human-readable format and should generally not be used for machine-to-machine transactions.
   Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2
  • jsonp: JavaScript Object Notation with Padding returns the data in the JSON format but wrapped within a specified callback argument for procedural calls.
   Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&callback=api&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

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://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&callback=test&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2

key

The key parameter is a Database Manager defined API access code. The key used in the OJ_Break API reference is for testing and example purposes only.

Getting a Key

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

Shown are the username and passwords fields to sign into Database Manager. If an account needs to be created, clicking the sign up button redirects to an account creation page.


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

The Manage API Access link is shown. This link will bring up the API Access page.


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

Shown here is the API Key button on the API Access page. Clicking the Set Up Access button will reveal a unique database key.

Responses

Every call to the API, regardless of the format, will return three main articles of information: code, message, and data.

Roughly, the arrangement of the response will be similar to: code:[code], message:[code message], data:[method return]

code

A popup containing an error message stating that access is denied to the API.
An example of an error alert. Error code 901 is shown to help describe possible causes.

The code key/tag contains a three digit number whose value depends on the state of the API request. Below is a list of all possible codes and their significance.

  • 100: Success
  • 900: Error
  • 901: Error
  • 902: Error
  • 903: Error

message

The message response will accompany the received code number as an explanation for the state of the API request. Below is a list of the possible codes and their cooresponding messages.

  • code 100: message: "API resource successfully retrieved"
  • code 900: message: "API resource not specified"
  • code 901: message: "API resource could not complete request (reasons: resource not available, parameters missing, malformed parameter value, or internal system error)"
  • code 902: message: "API key is either missing or invalid"
  • code 903: message: "Server is not authorized to use the API for the specified API key"

data

All of the returned information from the API call will be found organized in the data key/tag. This information will only be present with a successful API retrieval.

Retrieved from "https://xbiod.osu.edu/index.php?title=OJ_Break_API_Access&oldid=2017"