1.17 Web API

WebPortal API

The VS.WebAPI.Admin was designed to enable creating your own portals or integrating with your own CRM applications.

Default application name: PortalWebAPI

Default url at which application is installed: http://ip_address_or_dns/VS.WebAPI.Admin/

To find out what version of WebPortal API was installed enter the following url:

http://ip_address_or_dns/VS.WebAPI.Admin/api.test

In the result the version will be returned as shown on Fig 1.

To get information about each available method in the API enter the following url:

http://ip_address_or_dns/VS.WebAPI.Admin /Docs/index.html for html generated documentation

http://ip_address_or_dns/VS.WebAPI.Admin /metadata for automated documentation

The WebPortal API built-in help guide provides useful information about each available method in the API. Once the url http://ip_address_or_dns/VS.WebAPI.Admin /Docs/index.html is opened a full list of methods is presented as in Fig 2. To view the details of a selected method select it from the left menu; in main window additional information will be shown as in the example method in Fig 3.

The example method AdminGetTariffName (Fig 3) provides information about the list of available attributes in the Members tag:

CurrencyId
Name
PageOffset
PageSize

In Remarks it provides information that the method returns: Return tariffs. Also, requirements are shown: Require admin authentication.

The service allows you to communicate in HTTP POST and for selected methods in GET. It is recommended to use JSon format. To access API methods authorization is required. An API client can log in to each method separately or to use session information. Login by default is turned on with passwords hashed in SHA1. The account for authorization is taken from VSM module Users as shown in Fig 4. To pass login information it is required to add the #admin suffix, e.g api_login#admin.

List of all methods available for:

ApiPortal - user level

ApiAdmin - admin level

Various examples of usage:

PHP - Zend:

public function GetGreetingsTest()
   {       
       $baseUrl =  'http://localhost/PortalWebAPI/json/syncreply';
   
       $client = new Zend_Http_Client($baseUrl . '/GetGreetings');
       $client->setAuth('LOGIN', sha1('PASSWORD'));
       $client->setHeaders('Content-Type', 'application/json');
 
       $send = array(
           "isForPBXAutoattendant" => false         
       );
 
       try
       {
           $data = json_encode($send);
           //print_r($data);
           $client->setRawData($data);
           
           $resonse = $client->request("POST");
 
           print_r($resonse);
       }
       catch (Exception $e)
       {
           print_r($e);
       }
   }

PHP - Drupal:

$base_url = "http://localhost/PortalWebAPI/json/syncreply";
 
$login = 'LOGIN';
 
$pass = 'PASSWORD';
 
$auth = 'Basic '.base64_encode($login . ':' . sha1($pass));
 
      
  $send = array(
            "isForPBXAutoattendant" => false         
        );
         
$options = array(
 
      'method' => 'POST',
 
      'timeout' => 30,
 
      'headers' => array('Content-Type' => 'application/json','Authorization' => $auth ),
 
      'data' =>  json_encode($send)
);

C#:

Basic authentification using header Authorization and Base64 encoding with RestSharp

var restClient = new RestClient("http://IP/PortalWebAPI/");
 
var request = new RestRequest("/AdminLogOn", Method.POST);
   request.AddHeader(HttpHeaders.Authorization, string.Format("Basic {0}",
         Convert.ToBase64String(ASCIIEncoding.UTF8.GetBytes(string.Format( "{0}#admin:{1}", "login", GetSHA1("password"))))));
   RestResponse<AdminLogOnResponse>
 response = 
(RestResponse<AdminLogOnResponse>)restClient.Execute<AdminLogOnResponse>(request)

Example with C# library RestClient from ServiceStack.Common (http://servicestack.net/)

JsonServiceClient client = new JsonServiceClient(PortalAppConfig.ApiBaseUrl);
client.UserName = login + "#admin";
client.Password = GetSHA1(password);
 
AdminLogOnResponse response = client.Send<AdminLogOnResponse>("POST", "AdminLogOn", null);

Calculating SHA1 example

public static string GetSHA1(string val)
       {
           SHA1 sha = new SHA1CryptoServiceProvider();
           return BitConverter.ToString(sha.ComputeHash(Encoding.Default.GetBytes(val))).Replace("-", "").ToLower();
       }

HTTP (fiddler):

Request

POST to url : http://IP/PortalWebAPI/logon?format=json
User-Agent: Fiddler
Authorization: Basic Y29tbW9uOjk0YzhjMjFkMDg3NDBmNWRhOWVhYTM4ZDFmMTc1YzU5MjY5MmYwZDE=
Host: localhost
Content-Length: 2

Response

HTTP/1.1 200 OK
Server: IIS
Date: Tue, 10 Jul 2012 14:32:55 GMT
X-AspNet-Version: 2.0.50727
X-Powered-By: ServiceStack/3,83 Win32NT/.NET
Set-Cookie: ss-id=PiY6ZicZh0mHqLn3kn7YLw==; path=/
Set-Cookie: ss-pid=aNEXjNDLX0CgfLvIQQSC+g==; expires=Sat, 10-Jul-2032 14:12:52 GMT; path=/
Cache-Control: private
Content-Type: application/json; charset=utf-8
Content-Length: 328
Connection: Close
 
{"idClient":1,"clientType":32,"tariffId":1,"tariffName":"Retail","currencyId":1,
"currencyName":"USD","isPBXSubAccount":false,"isPBXMainAccount":false,
"firstName":"Adam","lastName":"Smith","login":"common","eMail":"newEmail@demo.com",
"resellerId":-1,"accountState":389.6800,"creditAllowed":0.0000,"creditBalance":389.6800}

PHP (Without frameworks):

Admin Login

<?php
     
echo '<p>WebAPI PHP Demo</p>';
  
$baseURL = 'http://localhost/VS.PortalWebAPI'; // WebAPI BaseURL
  
$userName = "m"  . "#admin"; // admin userName with suffixAdmin
$userPasword = 'ok'; // admin password
  
$sendURL = $baseURL . '/json/syncreply/AdminLogOn';
  
echo '<p>Send url: ' . $sendURL . '</p>';
  
$passwordHash = sha1($userPasword);
  
echo '<p>User name ' . $userName . '</p>';
echo '<p>Password sha1 hash ' . $passwordHash  . '</p>';
  
$data = '{}';
echo '<p>Send json data ' . $data . '</p>';
  
$authData = base64_encode($userName . ':' . $passwordHash);
  
  
$headers = "Authorization: Basic " . $authData  . "\r\n";
$headers = $headers . "Content-type: application/json" . "\r\n";
$headers = $headers . "Content-Length: " . strlen($data) . "\r\n";
  
echo '<p>Send headers ' . $headers . '</p>';
  
$options = array(
    'http' => array(
        'method'  => 'POST',
        'header'  => $headers,        
        'content' =>  $data
    ),
);
$context  = stream_context_create($options);
  
$result = file_get_contents($sendURL, false, $context);
  
var_dump($result)
 
?php>

Get Tariffs Names

<?php     
echo '<p>WebAPI PHP Demo</p>';
 
$baseURL = 'http://localhost/PortalWebAPI'; // localAdress
 
$userName = "m"  . "#admin"; // admin userName with suffixAdmin
$userPasword = 'ok'; // admin password
 
$sendURL = $baseURL . '/json/syncreply/AdminGetTariffNames';
 
echo '<p>Send url: ' . $sendURL . '</p>';
 
$passwordHash = sha1($userPasword);
 
echo '<p>User name ' . $userName . '</p>';
echo '<p>Password sha1 hash ' . $passwordHash  . '</p>';
 
$json = array("name" => "",
"currencyId" => -1,
"pageOffset" => 0,
"pageSize" => 100
);
 
 
 
$data = json_encode($json);
 
echo '<p>Send json data ' . $data . '</p>';
 
$authData = base64_encode($userName . ':' . $passwordHash);
 
 
$headers = "Authorization: Basic " . $authData  . "\r\n";
$headers = $headers . "Content-type: application/json" . "\r\n";
$headers = $headers . "Content-Length: " . strlen($data) . "\r\n";
 
echo '<p>Send headers ' . $headers . '</p>';
 
$options = array(
    'http' => array(
        'method'  => 'POST',
        'header'  => $headers,        
        'content' =>  $data
    ),
);
$context  = stream_context_create($options);
 
$result = file_get_contents($sendURL, false, $context);
 
var_dump($result)
 
?>

Soap 1.2 in PHP (Not recommended, better use JSon):

$apiBase = 'http://localhost:2629/';
$login = 'common';
$pass = 'common';
  
$hashPass = sha1($pass);
  
echo 'Load Payments for client with SOAP 1.2';
  
$webApi = new SoapClient($apiBase . 'soap12' , 
    array(
    "trace" => TRUE,
    "exceptions" => FALSE,
     "soap_version" => SOAP_1_2,    
     "login" => $login, 
    "password" => $hashPass));
  
  
$req = '<GetPayments xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/VS.PortalWebAPI.API">
  <PageOffset xmlns="http://schemas.datacontract.org/2004/07/VS.PortalWebAPI.API.SupportTypes">0</PageOffset>
  <PageSize xmlns="http://schemas.datacontract.org/2004/07/VS.PortalWebAPI.API.SupportTypes">100</PageSize>
  <FromDate>2013-01-01T00:00:00</FromDate>
  <ToDate>2014-01-01T00:00:00</ToDate>
</GetPayments>
';
  
  
//var_dump($webApi->__getFunctions());
//var_dump($webApi->__getTypes());
  
  
  
$result = $webApi->__soapCall("GetPayments", array(new SoapVar($req, XSD_ANYXML) ), 
		array("location " => $apiBase . '/xml/syncreply/GetPayments'));
  
print_r($result);
  
$send = $webApi->__getLastRequest();
  
print_r($send);
  
$result = $webApi->__getLastResponse();
  
print_r($result);

Figures

Click on a thumbnail to enlarge image

Fig. 1 - How to check WebPortal API versions

Fig. 2 - Full list of available methods

Fig. 3 - Details of selected method

Fig. 4 - API account information for authentication

Voipswitch documentation

1.17 Web API

WebPortal API

Various examples of usage:

See also

Figures

Related content