ipernity / PHP API Kit (v0.9)

This PHP API Development Kit requires PHP 5.2 or higher and CURL extension. This toolkit provides some basic functions to perform API calls and user authentication. Results can be returned in JSON, XML or serialized PHP.

Keep your API secret safe.

Installation

With PEAR

pear install -of https://s.ipernity.com/E/API_Kits/PHP/Iper_API/Iper_API-latest.tgz

Manually

Download Iper_API, unzip (tar/gz) and copy API.php in your website directory.

Demo

require 'API.php';

$api = new Iper_API(array('api_key'=>'8da10d4c00000001155dac4aa33cb785',
                          'secret'=>'966f6ff8c3ceba3a',
                          'format'=>'json'));

$r = $api->request('test.echo',array('echo'=>"you're smart!"));

if ( $r )
{
  print 'API replied: '.$r['echo'];
}
else
{
  print 'An error occured: '.$api->getErrorMessage();
}

Methods

function Iper_API(conf)

The class constructor. Uses setConf(conf) to set configuration values.

function setConf(conf)

conf is an array() of configuration parameters:

• api_key : your API key.
• secret : your secret.
• format : the desired output format. Values are : xml, json or php. Default is json.

JSON responses are decoded using json_decode(data,true) with assoc boolean true by default. Change the class property $api->_json_assoc to false if you prefer to receive a JSON object.

function setAppName(string $name)

Enter your application name if you'd like it to be sent in the HTTP User-Agent header.

function request(string $method, [array $params], [boolean $with_auth_token])

Parameters :

• method : the API method name.
• params : an array of parameters to send. (no need to precise api_url).
• with_auth_token : if set to true, automatically add the auth_token parameter to the request.

The request class method will take care of signing your request.

Returns :

• false : if the request failed. Check getErrorCode() and getErrorMessage() to see what happened.
• object|array : the result is sent in the requested format (xml/json/php).

function getAuthUrl(array $perms, [string $frob])

Parameters :

• perms : an array of permissions. ex : ['perm_doc']=>'write', 'perm_network'=>'read'].
• frob : an optional frob (for desktop authentication).

Returns : an URL

function getFrob()

Uses the request() method to perform an auth.getFrob API call. Returns a frob or false.

function getToken(string $frob)

Uses the request() method to perform an auth.getToken API call. Returns a token or false. When successful, the authentication information is stored into the $this->_auth property.
Authenticated calls can be done by adding the auth_token in the request parameters or by setting the flag with_auth_token (see the request() function).

function checkToken(string $token)

If the token is omitted the function will check the current token (if getToken() was called earlier). Returns a true or false. When successful, the authentication information is stored into the $this->_auth property.

function getAuth()

Returns the $this->_auth array.

function unauthenticate()

Removes authentication information e.g. resets $this->_auth.

Another demo...

// we assume this script is your callback url.

require 'API.php';

$api=new Iper_API(array('api_key'=>'6fa87ba500002712bd4eed6020f3bd72',
		        'secret'=>'e9a599f0cf6ce193'));

$api->setAppName('My supercool app');

// authenticate
if ( $_GET['frob'] )
{
  $token = $api->getToken($_GET['frob']);
  if ( ! $token ) die($api->getErrorMessage());

  // call with auto-authentication

  $r = $api->request('account.getQuota',array(),true);

  var_dump($r);

}
else
{
  $url = $api->getAuthUrl(array('doc'=>'write'));
  print '<a href="'.$url.'">click here to authorize this app</a>';
}

One last thing...

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