Difference between revisions of "OJ Break API Access"
(→Getting a Key) |
(→code) |
||
| Line 59: | Line 59: | ||
'''code:[''code''], message:[''code message''], data:[''method return'']''' | '''code:[''code''], message:[''code message''], data:[''method return'']''' | ||
=== ''code'' === | === ''code'' === | ||
| − | [[File:API_Access_tut_error.png|alt=A popup containing an error message stating that access is denied to the API.]] | + | [[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.]] |
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. | 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. | ||
Revision as of 16:20, 9 December 2014
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.
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. In the example below, the method getTaxonStats needs the parameter tnuid to return the desired 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 received 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/getTaxonStats?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/getTaxonStats?tnuid=30148&format=xml&key=FBF57A9F7A666FC0E0430100007F0CDC
- 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://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 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.
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.
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
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 method will be found organized in the data key/tag. This information will only be present with a successful API retrieval.
