TutorTrove API

TutorTrove provides an API for accessing the TutorTrove Whiteboard

The TutorTrove API allows you to call methods on the TutorTrove servers from your own site. Interaction with the API uses the standard HTTP protocol and all data is returned in the JSON format.

Overview

Authentication

The TutorTrove API uses the OAuth 1.0 Consumer Request protocol to authenticate each transaction. This ensures that only users with appropriate credentials will have access to secure data.

Location

The API v1 root URL is located at https://api.tutortrove.com/v1/

PHP Library Usage

To make accessing the API easier, a PHP library is available to you. It has built in support for the OAuth authentication protocol and will allow you to access secure data without the need to encrypt anything.

1. Download the API package

The PHP API package can be downloaded here: tutortrove_php_api_v1.zip

2. Get API Keys

In order to access the API, you must have both two API keys: a public key and a private key. You will have to have an account on Tutor Trove and will need to request the keys from us directly.

3. Unzip and Install The TutorTroveAPI Library

Inside the API package, there are two sample PHP files and a directory called TutorTroveAPI. Place the TutorTroveAPI package at a convenient place in your application.

4. Include and Initialize API access

To get started, include the base class, TutorTrove.php:

include '/path/to/TutorTroveAPI/TutorTrove.php';

Next, you'll need to define your public and private keys and create a new TutorTrove object:

TutorTrove::$public_key = 1234;
TutorTrove::$private_key = "abcdefghijklmnopqrst";

By default, the API connects over SSL to https://api.tutortrove.com. You can, instead, set it to connect over standard http by including the following:

TutorTrove::$use_https = false;

5. Call an API method.

For example, the "test" method merely checks whether your OAuth credentials and configuration are working:

<?php
/* sample API application */

include "TutorTroveAPI/TutorTrove.php";

TutorTrove::$public_key = 1234;
TutorTrove::$private_key = "abcefghijklmnopqrstuvwxyz";

$url = TutorTrove::test();

echo file_get_contents($url);

Loading the Tutor Trove Whiteboard in an iFrame

Alright, time to do something useful with this API. This method generates an OAuth secured URL for a user to access a specified Whiteboard, using the TutorTrove_SSO Library.

1. Do steps 1, 2, 3, 4 above

<?php

/* whiteboard_iframe_demo API application */

include "TutorTroveAPI/TutorTrove.php";

TutorTrove::$public_key = 1234;
TutorTrove::$private_key = "abcefghijklmnopqrstuvwxyz";
TutorTrove::$use_https = false;
Note that we recommend disabling https for the Whiteboard iframe. Our audio-video chat runs over unsecured http, so in Internet Explorer and some other browsers, users will see warnings about secure/insecure content if you run the Whiteboard over https

2. Populate the request array

Build an associative array with the relevant fields for logging the user into the Whiteboard 
required fields


recommended fields

3. Call the TutorTrove_SSO::whiteboard method

Use the associative array from above as the argument for this method. A url is returned: 
$url = TutorTrove_SSO::whiteboard(array(

	"whiteboard_hash" => "abc123",
	"whiteboard_title" => "Test Session",
	"user_type" => "tutor",
	"user_id" => 123,
	"user_name" => "Bob",
	"user_skype" => "bobbo"
));

4. Render an iframe with the above-generated url


<html>
	<body style='padding:0px; margin:0px'>
		<iframe width='100%' height='100%' frameborder='0'
			 src='<?=$url?>' >
		</iframe>
	</body>
</html>

5. Put it altogether!

Look in whiteboard_iframe_demo.php in the PHP API Package to see an example of the all of the pieces at once.