Créer un compte
Loading....

Introduction

As a developer you can create applications and add them to your sites taking advantage of MyCombi existing user base. You host the application, which means that you are in full control of your app at all times.

Setting up an APP

In order to interact with MyCombi you need to first set up an application on MyCombi.net.

This can be done by accessing
Apps >> Create an App or by visiting this link directly : http://mycombi.net/apps/add/

Once you have created the App you will get an APP ID. This unique ID is needed to communicate with MyCombi to verify you have access to the site's data.

APP On or Off the Site

You can create an APP with MyCombi to either be displayed on the site within an iframe or on your own site, in this case, visitors would leave the client's MyCombi site and land on your site. You will still need to host the apps on your own web server regardless of the method you choose. The main difference between these 2 modes of accessing the apps would is that using the iFrame method , users will access your app without leaving MyCombi , while the second method would mean users would be able to view the app on your own site while using their MyCombi identitied. This choice depends on what sort of an application you plan on building. In this documentation, we will be creating an APP that will not be displayed on a MyCombi site. The main difference between the two, is how you request a token, which we use as a secure method of authentication.

Make sure to edit your APP and set Will your App be on this site? to No. Next, click on URL and paste the URL to your site, where the APP is located in Return URL. This URL is where we send the user once they have installed your APP on the MyCombi site. If they have already installed the APP we will simply create a new token for them, which you will later use to authenticate the user.

Requesting a Token

In all of our examples we will be using PHP , but you can use any programming language of your choice, as the basic idea will be the same. In order to request a token you can either provide a link where your users would have to click or simply send them to your APP on the MyCombi site like this
header('Location: http://MyCombi.net/auth.php?key=[YOUR_APP_ID_HERE]');
exit;

Once they have reached this page it will either ask them to install the APP or if they have already done that, send them to your Return URL.

When we send the user back to your Return URL we pass along 2 GET parameters. It will look similar to this

http://www.YourSite.com/?auth=1&key=6f9597996e86b7b2318edd6af71ab5bc
First, we have auth. This is simply used to identify that this return is for authentication purposes. Next, we have key. This is a unique key for this specific user, which can only be used once. If the user would re-authenticate themselves you will get a new key.

With this key we can now request our token. You can request a token like so.

$oToken = json_decode(file_get_contents('http://MyCombi.net/token.php?key=' . $_GET['key']));
If the key is valid it will return a token
stdClass Object
(
    [token] => LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUc4d0RRWUpLb1pJaHZjTkFRRUJCUUFEWGdBd1d3SlVBdXF5MElhOEorZmM1VXM5NWVUYXFVL2o0Q29ncHV4MQo2ako5L1h6K2lVME9IOVhKVlVXcGh4SUh2b2VYcy82RFUwZjJGUWhLclNSdTY3cVRUc2pCaXpWUlZ2dVZCSVlKCnFSeVBMUmErTkdWbXNOcS9BZ01CQUFFPQotLS0tLUVORCBQVUJMSUMgS0VZLS0tLS0K
)	
You will notice right away this token is very long and will be used every time you make a request to the sites API.

To simplify this routine you can store a users token by using a PHP $_SESSION. This will save you from constantly authenticating a user for each request. Here you will find a working example of this routine.


session_start();

// API App ID
define('APP_ID', '[YOUR_APP_ID_HERE]');

// Place MyCombi site URL here
define('SITE_URL', 'http://mycombi.net/');

// User is not logged in
if (!isset($_GET['auth']) && !isset($_SESSION['token']))
{
	header('Location: ' . SITE_URL . 'auth.php?key=' . APP_ID);
	exit;
}

// Check to see if we should request a token for the user.
if (isset($_GET['auth']) && isset($_GET['key']))
{
	$oToken = json_decode(file_get_contents(SITE_URL . 'token.php?key=' . $_GET['key']));
	if (isset($oToken->token))
	{
		$_SESSION['token'] = $oToken->token;

		echo 'Successfully got a token: ' . $oToken->token;

		// Here is where you can use a header('Location:'); to send the authenticated user.
	}
}

Sending a Request

Now that we have a token we can send API requests to the server. When sending a request we advice to use CURL and send it as a $_POST. In this example for the sake of simplicity we will be sending a request using $_GET.
$oReturn = json_decode(file_get_contents('http://MyCombi.net/api.php?token=' . $_SESSION['token'] . '&method=user.get'));
You will notice in the code above we used $_SESSION['token'] as the token, which is what we used earlier to store the token we recently created. Next, you will notice method. This is the API request to the site, which in this case will get the users information of the person that is logged in.

Understanding an API Response

If you were to print_r() the request above the API response would look something like this
stdClass Object
(
    [api] => stdClass Object
        (
            [total] => 0
            [current_page] => 
        )

    [output] => stdClass Object
        (
            [user_id] => 3185
            [user_name] => app-demo
            [joined] => 1358329698
            [gender] => Male
            [country_iso] => CM
            [full_name] => App Demo
            [email] => app-demo@MyCombi.com
            [full_name_link] => App Demo
            [photo_50px] => http://MyCombi.net/file/pic/user/2013/01/c0fdf23aeae0e8219a4a9d8d7723d3d1_50.jpg
            [photo_50px_square] => http://MyCombi.net/file/pic/user/2013/01/c0fdf23aeae0e8219a4a9d8d7723d3d1_50_square.jpg
            [photo_120px] => http://MyCombi.net/file/pic/user/2013/01/c0fdf23aeae0e8219a4a9d8d7723d3d1_120.jpg
            [photo_original] => http://MyCombi.net/file/pic/user/2013/01/c0fdf23aeae0e8219a4a9d8d7723d3d1.jpg
            [photo_50px_link] => App Demo
            [photo_50px_square_link] => App Demo
            [photo_120px_link] => App Demo
            [photo_original_link] => App Demo
            [profile_url] => http://MyCombi.net/app-demo/
        )

)

First, you will notice we have [api] => stdClass Object. This stores useful information such as the total number of items a request could have and the current page we are on. This is mainly used if you are browsing for example photos, which can contain hundreds and we only list 10 per page.

The [output] => stdClass Object stores the important information we are requesting, which in this case is the active user.

Working with Modules

To the left of this page you will find a list of Modules.

With each module we provide detailed information on how you can interact with that module and all the actions it provides.

With each action you will find PARAMS and RETURN. PARAMS display the information you can pass with a call. For example let's take the action blog.add as an example, which can be found here.

This action has title and text as required parameters. So creating a call to create a blog would look like

$sPost = 'token=' . $_SESSION['token'] . '&method=blog.add&title=This is a test title&text=Some text for my blog';

$hCurl = curl_init();
curl_setopt($hCurl, CURLOPT_URL, 'http://MyCombi.net/api.php');
curl_setopt($hCurl, CURLOPT_HEADER, false);
curl_setopt($hCurl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($hCurl, CURLOPT_SSL_VERIFYPEER, false);	
curl_setopt($hCurl, CURLOPT_POST, true);
curl_setopt($hCurl, CURLOPT_POSTFIELDS, $sPost);
$sData = curl_exec($hCurl);
curl_close($hCurl);
$oReturn = json_decode(trim($sData));
You will notice directly that in this example we used CURL. The reason for that is we were now posting text with spaces and other characters and this is better suited using CURL.

RETURN displays all the possible data we would be returning. So if you were to print_r(); the above request we would get something like

stdClass Object
(
    [api] => stdClass Object
        (
            [total] => 1
            [current_page] => 
        )

    [output] => stdClass Object
        (
            [id] => 55
            [title] => This is a test title
            [likes] => 0
            [permalink] => http://MyCombi.net/blog/55/this-is-a-test-title/
            [content] => Some text for my blog
            [created_by] => App Demo
            [created_by_url] => http://MyCombi.net/app-demo/
        )

)