ipernity / JavaScript API Kit (v0.9)

This toolkit provides some basic functions to perform API calls and user authentication. Results can be returned in JSON or XML.

As you may know, AJAX calls must be done from the same server. This is the reason why we provide a PHP proxy (requires CURL). If you use a different language you will need to code your own proxy. Feel free to send us any codes you wrote or links if you'd like them to be included in the API kits page.

How to use

1. First, choose the javascript you need

• api.standlone.js (uses no javascript frameworks)
• api.mootools.js (requires mootools 1.2)

2. Add this script to your page

<script type="text/javascript" src="Iper_API.js"></script>

3. Configure your proxy

Download the PHP proxy script (requires CURL): proxy-0.9.gz and configure the following parameters:

• API_KEY : If set, you will not need to precise your api_key into you javascript code. This is the safest way to keep your api_key hidden.
• API_SECRET : configure your API secret to sign the API calls.
  Remember to keep your API secret... secret!

And start writing your API calls in minutes:

IPER.API.api_key="YOUR_API_KEY";
IPER.API.proxy="/your/proxy.php";
IPER.API.debug = true;             // turn debugging on (requires firebug console)

function test_echo_callback(success,response) { alert(response.echo); }

IPER.API.request('test.echo',{'echo':"It's working"},test_echo_callback);

Documentation

IPER.API

The ipernity methods are scoped into IPER.API.

IPER.API.request = function(method,params,callback,options,tries)

• method (str) : the API method to call.
• params (obj) : the parameters to send. ex: {'param' : 'value'}.
• callback (func) : function to execute when the request completes.
• options (obj) :
  • sync (bool) : [true|false] if set to true, the requests will be synchronous and freeze the browser during request.
  • delay (int) : delay the request of xxx milliseconds.
  • timestamp (bool) : [true|false] if set to true, add a timestamp parameter 'ts' to the request.

IPER.API.request('doc.search',{'text':'red car'},search_callback);
IPER.API.request('faves.docs.add',{'doc_id',12345},fave_callback,{'delay':1000});

callback = function(success,response,req,params,method)

• success (bool) : true if status="ok", false otherwise.
• response : the xml or json response.
• req : the xmlhttp instance.
• params : parameters sent.
• method : the method you called.

Callback example using JSON

function my_callback(success,response,req,params,method) {
  if ( success )
  {
    // you can explore the JSON response

    var docs = response.docs;
    ...
  }
  else
  {
    var code = response.api.code;
    var message = response.api.message;
    alert("error code="+code+" : "+message);

    // the error code 0 means that we could not establish a connection with the API
  }
}

Callback example using XML

function my_callback(success,response,req,params,method) {
  if ( success )
  {
    // you can explore the XML response

    var docs = response.getElementsByTagName("docs");
    ...
  }
  else
  {
    var api = response.getElementsByTagName("api")[0];
    var code = api.getAttribute("code");
    var message = api.getAttribute("message");
    alert("error code="+code+" : "+message);

    // the error code 0 means that we could not establish a connection with the API
  }
}

One last thing...

Have fun and let us know if you need any help.