Difference between revisions of "OJ Break API Access"
Jump to navigation
Jump to search
(→Getting a Key) |
(→Arguments) |
||
| (23 intermediate revisions by 2 users not shown) | |||
| Line 5: | Line 5: | ||
== Overview == | == Overview == | ||
| − | All API requests must be formatted by first selecting the OJ_Break library then specifying the API method | + | 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:// | + | The format for API calls is: '''''<nowiki>http://xbiod.osu.edu/OJ_Break/[method]?[argument1]=[value1]&...</nowiki>''''' |
| − | Example: '''''<nowiki>http:// | + | Example: '''''<nowiki>http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&format=html&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2</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. | ||
| Line 14: | Line 14: | ||
== 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. In the example below, the method | + | 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:// | + | 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 received 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:// | + | 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:// | + | 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. | * '''''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:// | + | Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&callback=api&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2 |
=== ''callback'' === | === ''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. | 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:// | + | Example: http://xbiod.osu.edu/OJ_Break/getTaxonInfo?tnuid=30148&callback=test&format=jsonp&key=FBF57A9F7A666FC0E0430100007F0CDC&version=2 |
=== ''key'' === | === ''key'' === | ||
| Line 39: | Line 42: | ||
==== Getting a Key ==== | ==== Getting a Key ==== | ||
| − | To get an API access key, go to the [http://osuc-mgr.osu.edu/ 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'''. | ||
| + | |||
| + | [[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. | 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 == | == Responses == | ||
| Line 51: | Line 62: | ||
'''code:[''code''], message:[''code message''], data:[''method return'']''' | '''code:[''code''], message:[''code message''], data:[''method return'']''' | ||
=== ''code'' === | === ''code'' === | ||
| − | The ''code'' key/tag contains a three digit number whose value depends on the state of the API request. | + | [[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 | * '''100''': Success | ||
* '''900''': Error | * '''900''': Error | ||
| Line 59: | Line 72: | ||
=== ''message'' === | === ''message'' === | ||
| − | The ''message'' response will accompany the received ''code'' number as an explanation for the state of the API request. | + | |
| + | 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'' '''100''': ''message'': '''"API resource successfully retrieved"''' | ||
* ''code'' '''900''': ''message'': '''"API resource not specified"''' | * ''code'' '''900''': ''message'': '''"API resource not specified"''' | ||
| Line 67: | Line 82: | ||
=== ''data'' === | === ''data'' === | ||
| − | All of the returned information from the | + | 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]] | [[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.
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, 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
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.
