(Quick Reference)

2 Getting Started - Reference Documentation

Authors: Prabhakar R, Thomas Vattakaven, Sravanthi M, Sandeep Tandekar, Rahul kumar Sinha

Version: 2.0

2 Getting Started

Api Modules

Quick Reference panel on the right hand side of the page gives access to api modules.

Basically API's are divided into modules depending on the type of object they are dealing with. A brief description about them is as follows.

ModuleDescription
speciesAPI to create, update and manage species pages on the portal
observationsAPI to manage, create and update observations on the portal
commentAPI to add, remove and get comments on various objects present in the portal
documentsAPI to manage documents uploaded on to the portal
searchAPI to search all modules
userAPI to get details of a user and update his settings.
usergroupAPI to list all usergroups and fetch information regarding them
statsAPI to get basic stats of the portal
speciesGroupAPI to get all species groups across which all information in the portal is arranged
registerAPI to register a new user, resend verification email and forgot password
loginAPI to do basic login and oauth login using facebook and google
logoutAPI to logout from the portal

Request Format

All requests except for the login and register apis should be authenticated. Only a logged in user can access them. Using login api you can generate a authentication token and it should be present in the header of every request by the name X-Auth-Token

APIs reading data from the portal just need this authentication token, but any api writing content in to the portal also needs an appKey. This is to identify the app and discourage putting in junk data into the portal using scripts. App Key can be generated from user profile page.

All requests are of the format

http://indiabiodiversity.org/api/$controller/$action/$id?

X-Auth-Token is the header key for providing authentication key and X-AppKey id the header key to provide app key for all write requests Accept header with values application/json, text/json can be provided to mention response format

Please email support [at] indiabiodiversity [dot] org to get a appkey

Response Format

Any response is of the format [success : true or false, status : HTTP status code, instance : object details if requesting for an object, model : any other params.

If success = false in the above response then there is corresponding msg and errors fields detailing the kind of the error.

A successful api request wil get 200 OK http status and any unauthenticated request will get 401 status with appropriate message saying either auth token is missing or app key is missing. If the method is not supported for any action you would get a 405 Method Not Allowed status.

Sample Applications

Few sample applications detailing the usage of the api are shown in below section.

IBP Android App

IBP Android App on Google play

IBP Observation Fetcher - Chrome Extension

  1. Chrome Extension using below rss feed
  2. RSS Feed
  3. Yahoo Pipes Info

IBP Moderator Mode App - by Rohit

Curate Observations

Simple login, logout and reading My observations

# Login : curl -X POST -H "Accept:application/json;v=1.0"  http://indiabiodiversity.org/api/login --data "username=emailId&password=password"

# My observations : curl -L -X GET -H "Accept:application/json;v=1.0" -H "X-Auth-Token:ov6eov262mr716sbg06b2d31kq5l13gi" http://indiabiodiversity.org/api/observation?user=1184

# Logout : curl -L -X POST -H "Accept:application/json;v=1.0" -H "X-Auth-Token:ov6eov262mr716sbg06b2d31kq5l13gi" http://indiabiodiversity.org/api/logout

Featured species

# Getting featured species list : http://indiabiodiversity.org/related/species?limit=10&offset=0&filterProperty=featureBy&filterPropertyValue=true
# Getting details of a particular species : http://indiabiodiversity.org/api/species/33485

Example :

Related observations by species name

http://indiabiodiversity.org/api/related/observation?webaddress=dragonflies_of_india&id=358179&limit=4&offset=0&filterProperty=speciesName&filterPropertyValue=Pseudagrion+decorum

Example :

Observation distribution by species name

# http://indiabiodiversity.org/api/related/observation?webaddress=dragonflies_of_india&filterProperty=speciesName&limit=-1&id=358179&fetchField=id,latitude,longitude,isChecklist,geoPrivacy&max=-1

Example :

Document Tags Cloud

# http://indiabiodiversity.org/api/document/tags

Example :

Top contributors of the week

$.get( "http://indiabiodiversity.org/chart/topContributors?max=10&webaddress=treesindia", undefined, function(data, textStatus, jqxhr ) {

$.each(data.htmlData, function (i, v) { $('#topContributors').append("<div class='entry'>"+v[0]+v[1]+"("+v[2]+")</div>"); }); }, 'json');

Example :

Distinct recommendation names

$.getScript( "http://indiabiodiversity.org/biodiv/js/species/observations/distinctReco.js", function(e) {
    $("#distinctRecoTableAction").unbind('click').click(loadDistinctRecoList).click();
});

Example :

Latest Observations

$.getScript( "http://indiabiodiversity.org/biodiv/js/species/relatedStory.js", function(e) {
    relatedStory([], "latestUpdatedObservations", "latestUpdatedObservations", "", "");
});

This code snippet uses jquery jcarousel plugin