Description:

Sippy XML-RPC API is developed to make it possible to integrate third party software with Sippy SoftSwitch.


General Information:


  • The XML-RPC is used as a communication protocol.
  • Access to this service is protected by HTTP-Digest authentication and optionally by SSL encryption.
  • The interface supports the <nil/> element to represent NULL values. There is no such or similar element in the XML-RPC specification but most implementations support it so it can be considered to be de-facto standard.
  • URL to access the service is https://<YOUR_SWITCH_IP>/xmlapi/xmlapi.

Access Control and Authentication


Normal Mode

In Normal Mode the XMLRPC client should authenticate itself with username and password, which will be used to restrict scope of the access to a particular Customer account.

Service is accessed on per Customer basis, you have to set the API check-box from the upper level customer in the Permissions for the sub-customer you want to let API usage (image below).

Authentication is performed using Web Login and API Password and requires Allow API Calls parameter to be enabled in "My Preferences" of the root user:



Or in the properties of any sub-customer for which an API calls should be enabled:



Don't forget to activate API for the sub-customer in the Permissions menu , otherwise your attempts to get some data via API will be unsuccessful:



Trusted Mode

There is also a trusted mode of operation, allowing to permit full access to a specified IP address or a range of IP addresses without performing username-based authentication. In order for the request to be treated as trusted, the IP of the calling HTTP client has to be present in the trusted_hosts table and no authentication has to be used. In trusted mode the customer scope limitation is not applied and requests can be made against any customer. This mode is intended mainly for use by switch components and external uses are discouraged.


In the case that trusted mode is not mentioned in the corresponding documentation, it's not guaranteed that this method supports such authentication.

Try authenticating yourself with Customer's Web Login and Api Password instead.


To supply proper audit logging information in trusted mode since 4.5 version, the caller should pass audit_info parameter. This parameter has struct type and consists of:

  • user_ip - the IP of original request. String.
  • user_agent - the User-Agent HTTP header from original request. String.
  • action_by - the login info of the original requester. String.

If some parameter of audit_info has not been supplied it will be complemented from properties of trusted XMLAPI-call.


CURL Utility

If you never worked with XML-API, then you can use our example how to retrieve the needed information via CURL tool. Below we have provided example for the method GetAccountInfo():

 

 curl -v -k --digest -u CustomerA:pass123 -d '<?xml version="1.0"?> <methodCall> <methodName>getAccountInfo</methodName> <params> <param> <value><struct> <member><name>i_account</name> <value><int>3</int></value> </member> </struct></value> </param> </params> </methodCall>' https://your.environment.com/xmlapi/xmlapi