How to use the Ikoula API

fr:Comment utiliser l'API d’Ikoula es:Cómo utilizar la API de Ikoula nl:Hoe de Ikoula API te gebruiken? zh:如何使用Ikoula的API

Introduction

IKOULA has an API allowing you to perform actions on the products associated with your customer account. Here is the URL of the API: https://api.ikoula.com

Documentation is available directly for each product.

Explications

For obvious security reasons, the Ikoula API requires authentication. This is based on a username, a password and a signature:

• The identifier is the email address used to connect to your Ikoula account or to the Extranet. The name of the parameter to transmit it is always login ;
• The password must be encrypted via a specific function using a public key provided by Ikoula crypted_password parameter) and base64_encode ;
• The signature is generated according to the parameters provided when calling the API.
• These parameters must always be passed in GET to the API!

WARNING:

For your API tests, you can, for example, use a temporary user dedicated to these tests. The use of password encryption with the Ikoula public key is essential in any production or non-short term context.
If the API calls are to be used via a script or a program, we recommend that you create a dedicated user for this purpose rather than using your classic extranet user.
Here, you have two possibilities:

• Create a sub-user directly from the home page of your extranet account (See the WIKI below for the creation of sub-users: How to create a sub-account?).
• Contact our support for the creation of an extranet user if needed.

Be careful not to forget to give him the rights to the desired services.

Encryption key

The public password encryption key is available at the following address: https://api.ikoula.com/downloads/Ikoula.API.RSAKeyPub.pem

Wrapper PHP

<?php 

// #################################################
// ####    ..:: Ikoula Hosting Services ::..     ###
// ####	   Wrapper for https://api.ikoula.com	 ###
// #################################################

class IkoulaAPI {

   /**
    * Email of Ikoula account
    * @var string Email account
    */
    private static $email = "EMAIL_ACCOUNT_IKOULA";

   /**
    * Password of Ikoula account
    * @var string Password account
    */
    private static $password = "PASSWORD_ACCOUNT_IKOULA";

   /**
    * Ikoula API URI
    * @var string Password account
    */ 
    private static $urlApi = "https://api.ikoula.com/";

   /** Public key path for encrypt data
    * @var string Path of public key
    * @see https://api.ikoula.com/downloads/Ikoula.API.RSAKeyPub.pem
    */ 
    private static $publicKeyPath = "/path/to/ikoula/public/key/Ikoula.API.RSAKeyPub.pem";
	
    /** Fonction for request Ikoula API
     * @param string $webservice Webservice for data
     * @param string $format JSON or XML
     * @param string $type HTTP Type (GET/POST)
     * @param array $params Params to add for request
     */
     public static function requestApi($webservice, $format, $type, $params = [])
     {
		// Add connexion information
		$params['login'] = self::$email;
		$params['crypted_password'] = base64_encode(self::opensslEncryptPublic(self::$password));
		$params['format'] = $format;

		// Generate signature
		$signature = self::createSignature($params);

		// Add signature for call
		$params['signature'] = $signature;

		// Curl init
		$ch = curl_init();

		if($ch)
		{
			// Create API URI
			$url = self::$urlApi.$webservice;
	
			// Add type request
			curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $type);

			// If parameters, we encode his 
			if(is_array($params) && count($params) > 0)
				$params_str = http_build_query($params);

			// If we use post, fix params
			if(strcasecmp("POST", $type) == 0)
			{
				// Fix POST data
				curl_setopt($ch,CURLOPT_POST, true);
				curl_setopt($ch,CURLOPT_POSTFIELDS, $params_str);
			}
			else
				$url .= (strpos($url,'?') === false ? '?' : '&').$params_str;
	
			// Create curl info
			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);
			curl_setopt($ch, CURLOPT_HEADER, false);
	
			// Exec request
			$data = curl_exec($ch);
	
			// Close curl object
			curl_close($ch);
	
			// Return response
			return($data);
		}

		return null;
    }

    /** Create signature with params
     * @param array $params Params to add for request
     * @return string Signature encoded
     */
    private static function createSignature($params = [])
    {
        // Signature to send
        $signature = null;

        // Verify parameters
        if (count($params) > 0)
        {
            // Sort params
            ksort($params);
            
            // Encode params
            $query = http_build_query($params);

            // Encode "plus "+"
            $query = str_replace("+", "%20", $query);

            // Transform in lowercase
            $query = strtolower($query);

            $public_key = "";

            // Verify if key file is present
            if (file_exists(self::$publicKeyPath))
            {
				// Get public key
                $public_key = trim(
                        str_replace(
                                array("\n", '-----BEGIN PUBLIC KEY-----','-----END PUBLIC KEY-----'), 
                                array('', '', ''), 
                                file_get_contents(self::$publicKeyPath)
                            )
                        );
            }

   			// SHA1 hash
            $hash = hash_hmac("SHA1", $query, $public_key, true);

    		// base64 encode
            $signature = base64_encode($hash);
        }

    	return $signature;
	}
	
	/** Fonction for crypt Ikoula password
	 * @param string $password Ikoula account password
	 * @return mixed Ikoula password encrypted, null if error
	 */
	private static function opensslEncryptPublic($password)
	{
		// Verify if key file exist
		if(file_exists(self::$publicKeyPath))
		{
			 // Verify if password is not empty
 			if(!empty($password))
			{
				// Get file content
				$publicKey = openssl_pkey_get_public('file://'.realpath(self::$publicKeyPath));
	
				// If we get file content without error
				if ($publicKey !== FALSE)      
				{
					// Encrypt password
					if(openssl_public_encrypt($password, $crypted, $publicKey) === TRUE)
						return $crypted;
					else
						return NULL;
				}
				else
					return NULL;
			}
			else
				return NULL;
		}
		else
			return NULL;
	}
}

Exemples d'utilisation

// Fix JSON header
header("Content-type: application/json");

// Get Exch schema for prestation
echo IkoulaAPI::requestApi("wsexch/schema-subscr", "json", "GET", ['subscr_id' => 999999999]);

// Get Flex VM for Ikoula Account
echo IkoulaAPI::requestApi("wsflex/list", "json", "GET", []);

// Get Flex VM for Ikoula Account
echo IkoulaAPI::requestApi("wsflex/list", "json", "GET", []);

// Get Platform list
echo IkoulaAPI::requestApi("wsplatform/list", "json", "GET", []);

// Get Platform dossiers
echo IkoulaAPI::requestApi("wsplatform/dossiers", "json", "GET", ['platform_id' => 999999999]);

// Get Billing conso for CloudStack prestation
echo IkoulaAPI::requestApi("wscs/conso-for-billing", "json", "GET", ['subscr_id' => '999999999', 'billing_id' => '1']);

// Reboot server
echo IkoulaAPI::requestApi("wsds/reboot-apc-request", "json", "GET", ['server_ip' => 'XXX.XXX.XXX.XXX', 'tempo' => '3']);

Adding Features

In the event of a feature request, contact technical support.