OJ Break API Access

From xBio:D Wiki
Jump to navigation Jump to search

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"