View Source

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/

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

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

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.

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#:

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)

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

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

HTTP (fiddler):

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

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):

<?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>

<?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

Voipswitch documentation > 1.17 Web API > pic1.png
Fig. 1 - How to check WebPortal API versions

Voipswitch documentation > 1.17 Web API > pic2.png
Fig. 2 - Full list of available methods

Voipswitch documentation > 1.17 Web API > pic3.png
Fig. 3 - Details of selected method

Voipswitch documentation > 1.17 Web API > VSMadmin.png
Fig. 4 - API account information for authentication

WebPortal API

Various examples of usage:

See also

Figures