Examples of using the API

en:Examples of using the API he:דוגמאות לשימוש ה-API ru:Примеры использования API ja:API を使用しての例 ar:أمثلة لاستخدام API zh:使用该 API 的示例 ro:Exemple de utilizare a API pl:Przykłady użycia interfejsu API de:Beispiele für die Verwendung der API nl:Voorbeelden van het gebruik van de API it:Esempi di utilizzo dell'API pt:Exemplos de como usar a API es:Ejemplos de uso de la API fr:Exemples d'utilisation de l'API

Introduction

How to use the API through some concrete and functional examples.

Functions for the examples

// Chemin local vers la clé publique téléchargée sur http://api.ikoula.com/downloads/Ikoula.API.RSAKeyPub.pem
define('API_PUB_KEY_PATH', dirname(__FILE__) . '/Ikoula.API.RSAKeyPub.pem');

<!--T:3-->
// Fonction de chiffrement du mot de passe via la clé publique Ikoula
function opensslEncryptPublic($password)
{
	// Vérification de la présence de la clé publique
	if(file_exists(API_PUB_KEY_PATH))
	{
		if(!empty($password))
		{
			// on récupère la clé public
			$publicKey = openssl_pkey_get_public('file://'.realpath(API_PUB_KEY_PATH));

			<!--T:4-->
// S'il n'y as pas eu d'erreurs lors de la récupération de la clé publique, on continue
			if ($publicKey !== FALSE)      
			{
				// Si chiffrement clé publique OK
				if(openssl_public_encrypt($password, $crypted, $publicKey) === TRUE)   
				{
					// Renvoie du mot de passe crypté
					return $crypted;       
				}
				else
				{
					return NULL;
				}
			}
			else
				return NULL;
		}
		else
			return NULL;
	}
	else
	{
		echo("Erreur - la clé publique n'est pas présente.\n");
		return NULL;
	}
}

<!--T:5-->
// Fontction de création de la signature en fonction des paramètres présents
function createSignature($params=array())
{
    $signature = null;

    <!--T:6-->
// Si il y a au moins un paramètre
    if (count($params) > 0)
    {
        //debug('create signature');
        //debug($params);
        
        // Triage des paramètres dans le sens croissant
        ksort($params);
        
        // Encodage des paramètres
        $query = http_build_query($params);

        <!--T:7-->
// Encodage des signes "plus "+"
        $query = str_replace("+", "%20", $query);

        <!--T:8-->
// Transformation de la chaîne de caractères en minuscule
        $query = strtolower($query);

        <!--T:9-->
$public_key = "";
        // Si le fichier existe, on va récupérer la clé
        if (file_exists(API_PUB_KEY_PATH))
        {
            $public_key = trim(
                    str_replace(
                            array("\n", '-----BEGIN PUBLIC KEY-----','-----END PUBLIC KEY-----'), 
                            array('', '', ''), 
                            file_get_contents(API_PUB_KEY_PATH)
                        )
                    );
        }

        <!--T:10-->
// Hashage des paramètres
        $hash = hash_hmac("SHA1", $query, $public_key, true);

        <!--T:11-->
// Encodage en base64
        $signature = base64_encode($hash);
    }

    <!--T:12-->
return $signature;
}

<!--T:13-->
// Fonction facilitant l'envoie des requêtes vers l'API Ikoula
function send_request ($rest, $url_param, $params=array())
{
	// initialisation de CURL
	$ch = curl_init();
	if($ch)
	{
		// Si on a des info on utilise l'api REST sinon on utilise l'api standard (WebService)
		if($rest)
			$url = "https://api.ikoula.com/rest/" . $url_param;
		else 
			$url = "https://api.ikoula.com/?r=" . $url_param;

		
		<!--T:14-->
// si on est en REST on rajoute le type d'appel (POST,DELETE,PUT,GET,...) sinon on passe en POST
		curl_setopt($ch, CURLOPT_CUSTOMREQUEST, ($rest)?$rest:"POST");
		// Si il y a des paramètres on les rajoute dans la requête
		if(is_array($params) && count($params) > 0)
		{
			$params_str = http_build_query($params);
		}
		if($rest=='POST')
		{
			// on rentre le nom de paramètre présent dans la requête
			curl_setopt($ch,CURLOPT_POST, true);
			curl_setopt($ch,CURLOPT_POSTFIELDS, $params_str);
		}
		else
		{
			$url .= (strpos($url,'?') === false ? '?' : '&').$params_str;
		}
			
		// On ajoute l'url
		curl_setopt($ch, CURLOPT_URL, $url);
		curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
		curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
		curl_setopt($ch, CURLOPT_HEADER, 1);
		curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
		// on vire les en-tête HTTP pour avoir directement le retour
		curl_setopt($ch, CURLOPT_HEADER, false);
	   
		// exécution de la requête
		$data = curl_exec($ch);
	   
		// fermeture de l'objet
		curl_close($ch);

		<!--T:15-->
// retourne la réponse
		return($data);
	}
	return null;
}

API calls

//login
$login = 'mail@test.com';
//on crypte le mot de passe
$crypted_password = base64_encode(opensslEncryptPublic('MOT_DE_PASSE_A_CRYPTER'));

<!--T:17-->
//liste des VM - retour en JSON

<!--T:18-->
//liste des paramètres que l'on souhaite envoyer à l'API (pour générer la signature)
$parameters = array('login' => $login, 'crypted_password' => $crypted_password, 'format' => 'json');
//on génère la signature
$signature = createSignature($parameters);
//on ajoute la signature dans les paramètres à envoyer lors de l'appel à l'API
$parameters['signature'] = $signature;
//on fait l'appel API
$data = send_request(false,'wsflex/vmlist',$parameters);
print_r($data); //appel WebService
$data2 = send_request('GET','vm/list',$parameters);
print_r($data2); //appel REST

<!--T:19-->
//informations d'une VM - retour en XML

<!--T:20-->
//liste des paramètres que l'on souhaite envoyer à l'API (pour générer la signature)
$parameters = array('login' => $login, 'crypted_password' => $crypted_password, 'format' => 'xml', 'subscr_id' => 12345);
//on génère la signature
$signature = createSignature($parameters);
//on ajoute la signature dans les paramètres à envoyer lors de l'appel à l'API
$parameters['signature'] = $signature;
//on fait l'appel API
$data = send_request(false,'wsflex/vminfo',$parameters);
print_r($data); //appel WebService
$data2 = send_request('GET','vm/'.$parameters['subscr_id'],$parameters);
print_r($data2); //appel REST

Common errors

Permission Denied

Means that the user used in the API does not have the right to access the requested information or perform the desired action

Unable to decrypt password

Means that the parameter crypted_password has been poorly encrypted or corrupted

Invalid credentials

Means that authentication has failed, and that the user is not so recognized

Invalid or missing signature

Means that the signature is not present in the parameters received by the API, or that it is invalid

Other lifts of errors are possible but will be contextual depending on the desired functionality.

This article seemed you to be useful ?

0

Vote

Sort by date Sort by score

Enable comment auto-refresher

You are not allowed to post comments.