API Client

Overview

This API client is an experiment that demonstrates the flexibility of UnifiedAPI. The client extends the existing Google's Client Library for PHP and enables you to write Apps easier. The extension handles all the steps necessary for an App to register and communicate with VoipNow:

• Dynamic App registration: registration of an App is a click away. Just configure the App and see how it automatically registers using your VoipNow credentials.
• App authorization: the OAuth 2 flow has never been so easy to master. You have to fill in your credentials and that's it.
• Create a valid, authorized UnifiedAPI REST request: you ask, the client delivers. You don't need to concern yourself with protocol implementation anymore.

The client uses a flexible object model based on UnifiedAPI's resources. That means you don't have to write protocol level code and only have to concern yourself with the business end of your software. This tutorial is structured in four sections:

1. Installation. Here you download Google's PHP Client Library and the UnifiedAPI Client. You also make a one line change to the Google Client.
2. Your App in 15 Minutes. Here you learn how to harness the power behind our software in a quick, down and dirty tutorial.
3. The Call Widget. We also wrote a widget to show you how to integrate UnifiedAPI into your existing website.
4. More Examples. If you want to see all of the operations on all of the resources UnifiedAPI has to offer, you must try this all-in-one demo.

Installation

In order to use the UnifiedAPI Client, you need a webserver with PHP 5.3 or higher installed. You also require the mcrypt extension for the encrypted storage class.

Download Google client library

Download and extract Google's client library for PHP (version 0.6). Download the archive containing the code from here and extract it to a path in your project or web root. (This path will be known as GOOGLE_CLIENT_PATH. e.g. /home/user/lib/google-api-php-client).

Download UnifiedAPI client

Download and extract the UnifiedAPI Client. Download the attached archive from here and extract it to a path in your project or web root. (This path will be known as UNIFIEDAPI_CLIENT_PATH. e.g. /home/user/lib/uapiclient).

Patch Google client library

Modify Google's client library. Edit <GOOGLE_CLIENT_PATH>/src/io/Google_REST.php. Change line 55 from:

    if ($code != '200' && $code != '201' && $code != '204') {

to:

    if ($code != '200' && $code != '201' && $code != '202' && $code != '204') {

Your app in 15 minutes

Using our SimpleCall code as a starting point, you can build a minimal App that handles registration, authorization and processes a form where you enter a number to call somebody.

App configuration

STEP 1: Copy the contents of <UNIFIEDAPI_CLIENT_PATH>/examples/simpleCall/ to a folder in your webroot.

STEP 2: Change the name of the copied config.php.default file to config.php.

STEP 3: Edit config.php and fill in the required values. An example stripped of comments is available below.

<?php
define('GOOGLE_API_CLIENT_BASE_PATH', '/home/user/lib/google-api-php-client/');
define('UNIFIEDAPI_CLIENT_BASE_PATH', '/home/user/lib/uapiclient/');
define('ENCRYPTED_STORAGE_FILE_PATH', '/home/user/confidential/crypt.store');
define('ENCRYPTED_STORAGE_KEY', 'lkiqA&%jh%ASDND!#AF');
$voipnowData = array(
	'extensions' => array(
		'phoneTerminal' => array('0139*001')
	)
);
$unifiedApiConfig = array(
	'use_objects' => true,
	'application_name' => 'SimpleCall',
	'registration_endpoint' => 'https://uapi.example.com/oauth/register.php',
	'registration_redirect' => 'https://simpleApp.example.com/index.php',
	'registration_homepage' => 'https://simpleApp.example.com',
	'registration_email' => 'user.simpleApp@example.com',
	'authClass'    => 'PSA_OAuth2',
	'basePath' => 'https://uapi.example.com/unifiedapi',
	'service_scope' => 'https://uapi.example.com',
	
	'oauth2_client_id' => '', // make it dynamic
	'oauth2_client_secret' => '',
	'oauth2_redirect_uri' => 'https://simpleApp.example.com/index.php',
	'oauth2_revoke_uri' => '', // UApi doesn't have revoke yet
	'oauth2_token_uri'  => 'https://uapi.example.com/oauth/token.php',
	'oauth2_auth_url'   => 'https://uapi.example.com/oauth/authorize.php',
	'oauth2_federated_signon_certs_url' => '',
	'clock_skew_secs' => '300',
	'auth_token_lifetime_secs' => '300',
	'max_token_lifetime_secs' => '86400',
	'services' => array(
		'unifiedapi' => array('scope' => 'https://uapi.example.com/uapi/')
	)
);

App registration

If the config file has an empty client id and client secret, then a registration link will be displayed when you first access the app. Don't worry, it's normal. When you press the link, you'll be redirected to your VoipNow server's App registration endpoint. In the registration screen you must fill in your VoipNow credentials. For more details, see App Registration.

App authorization

After registration or if client credentials were provided in the config file, you will be redirected to the authorization endpoint where the App will ask permission to access your data. You will have to fill in you VoipNow credentials again. After this, the access token has been generated and stored with encryption on the client. For more details, see App Authorization.

Make the call

Now you are able to access your SimpleCall app at https://<AppServerHost>/<PathToYourAppFolder>/index.php A very simple form should appear. You must enter the extension you want to call and.... presto, you're making a phone call the UnifiedAPI way.

The call widget

An example widget was written in jQuery and PHP to demonstrate how easy it is to write the server side code using the UnifiedAPI Client. The widget can also be used as a starting point to writing other such software. The client code is written in jQuery and CSS, while all HTML is created dynamically. These types of widgets are easy to integrate into your website because of their standalone nature.

Widget configuration

Please follow the next steps:

STEP 1: Copy the contents of <UNIFIEDAPI_CLIENT_PATH>/examples/callWidget/ to a folder in your webroot.

STEP 2: Change the name of the copied config.php.default file to config.php.

STEP 3: Edit config.php and fill in the required values. An example stripped of comments is available below.

<?php
define('GOOGLE_API_CLIENT_BASE_PATH', '/home/user/lib/google-api-php-client/');
define('UNIFIEDAPI_CLIENT_BASE_PATH', '/home/user/lib/uapiclient/');
define('ENCRYPTED_STORAGE_FILE_PATH', '/home/user/confidential/crypt.store');
define('ENCRYPTED_STORAGE_KEY', 'lkiqA&%jh%ASDND!#AF');
$voipnowData = array(
	'extensions' => array(
		'phoneTerminal' => array('0139*001')
	)
);
$unifiedApiConfig = array(
	'use_objects' => true,
	'application_name' => 'CallWidget',
	'registration_endpoint' => 'https://uapi.example.com/oauth/register.php',
	'registration_redirect' => 'https://www.example.com/widget/install.php',
	'registration_homepage' => 'https://www.example.com',
	'registration_email' => 'user.callWidget@example.com',
	'authClass'    => 'PSA_OAuth2',
	'basePath' => 'https://uapi.example.com/unifiedapi',
	'service_scope' => 'https://uapi.example.com',

	'oauth2_client_id' => '', // make it dynamic
	'oauth2_client_secret' => '',
	'oauth2_redirect_uri' => 'https://www.example.com/widget/install.php',
	'oauth2_revoke_uri' => '', // UApi doesn't have revoke yet
	'oauth2_token_uri'  => 'https://uapi.example.com/oauth/token.php',
	'oauth2_auth_url'   => 'https://uapi.example.com/oauth/authorize.php',
	'oauth2_federated_signon_certs_url' => '',
	'clock_skew_secs' => '300',
	'auth_token_lifetime_secs' => '300',
	'max_token_lifetime_secs' => '86400',
	'services' => array(
		'unifiedapi' => array('scope' => 'https://uapi.example.com/uapi/')
	)
);

Widget installation

The widget uses an install script to acquire client credentials and to request an access token for authorizing subsequent request. To install the widget, access the install.php script through your browser (it should be located in the widget folder). A link will be displayed and, upon clicking it, you will be redirected to the registration endpoint of the server and, after that, to the authorization endpoint. For more details, see App Registration and App Authorization.

Add the widget to your website

Now you can add the widget to your website. Just drop in a line of code where you want to put it.

<? include_once('path/to/widget/folder/callWidget.php')

Try it out

Just access your website using your favorite browser. Now you can make phone call directly from your site.

More examples

An example App was written to demonstrate all of UnifiedApi's operations.

App configuration

Please follow the next steps:

STEP 1: Copy the contents of <UNIFIEDAPI_CLIENT_PATH>/examples/uapi/ to a folder in your webroot.

STEP 2: Change the name of the copied config.php.default file to config.php.

STEP 3: Edit config.php and fill in the required values. An example stripped of comments is available below.

<?php
define('GOOGLE_API_CLIENT_BASE_PATH', '/home/user/lib/google-api-php-client/');
define('UNIFIEDAPI_CLIENT_BASE_PATH', '/home/user/lib/uapiclient/');
define('ENCRYPTED_STORAGE_FILE_PATH', '/home/user/confidential/crypt.store');
define('ENCRYPTED_STORAGE_KEY', 'lkiqA&%jh%ASDND!#AF');
$voipnowData = array(
	'extensions' => array(
		'phoneTerminal' => array('0139*001', '0139*002', '0139*003'),
		'callback' => array('0003*007'),
		'conference' => array('0003*004'),
		'faxEnabled' => array('0003*001', '0003*002'),
		'queue' => array('0003*008'),
	),
	'faxTestFile' => __DIR__ . DIRECTORY_SEPARATOR . 'templates' . DIRECTORY_SEPARATOR . 'faxes' . DIRECTORY_SEPARATOR . 'testFax.txt'
);

$unifiedApiConfig = array(
	'use_objects' => true,
	'application_name' => 'MoreExamples',
	'registration_endpoint' => 'https://uapi.example.com/oauth/register.php',
	'registration_redirect' => 'https://more.example.com/index.php',
	'registration_homepage' => 'https://more.example.com',
	'registration_email' => 'user.moreExamples@example.com',
	'authClass'    => 'PSA_OAuth2',
	'basePath' => 'https://uapi.example.com/unifiedapi',
	'service_scope' => 'https://uapi.example.com',

	'oauth2_client_id' => '', // make it dynamic
	'oauth2_client_secret' => '',
	'oauth2_redirect_uri' => 'https://more.example.com/index.php',
	'oauth2_revoke_uri' => '', // UApi doesn't have revoke yet
	'oauth2_token_uri'  => 'https://uapi.example.com/oauth/token.php',
	'oauth2_auth_url'   => 'https://uapi.example.com/oauth/authorize.php',
	'oauth2_federated_signon_certs_url' => '',

	'clock_skew_secs' => '300',
	'auth_token_lifetime_secs' => '300',
	'max_token_lifetime_secs' => '86400',
	'services' => array(
		'unifiedapi' => array('scope' => 'https://uapi.example.com/uapi/')
	)
);

App registration

If the config file has an empty client id and client secret, then a registration link will be displayed when you first access the app. Don't worry, it's normal. When you press the link, you'll be redirected to your VoipNow server's App registration endpoint. In the registration screen you must fill in your VoipNow credentials. For more details, see App Registration.

App authorization

After registration or if client credentials were provided in the config file, you will be redirected to the authorization endpoint where the App will ask permission to access your data. You will have to fill in you VoipNow credentials again. After this, the access token has been generated and stored with encryption on the client. For more details, see App Authorization.

Make the call

Now you are able to access the examples at https://<AppServerHost>/<PathToYourAppFolder>/index.php A menu is available on the left side of the screen. It consists of all the resources available in UnifiedAPI and all of the operations you can perform on those resources.

See Menu Screen

See List Example Screen