Please note that the SOAP API is now deprecated, and will be removed in a future version. Pleas use the JSON API instead.

Introduction

Enswitch includes a full SOAP API to allow 3rd party applications to integrate with Enswitch. The SOAP API is capable of everything the Enswitch web interface is capable of, as they both access the same underlying functions. These functions provide:

  • Authentication. Most functions take a username and password as the first two parameters, and check these against the people table in the database. Therefore accounts for SOAP access can be made on the Enswitch web interface under Features » People.
  • Checking whether the authenticated user may invoke this function. This is done by checking the person's user status from the database. For example, users without system owner or reseller access may not call functions affecting other customers, nor will any of the functions they may call return data about any other customers to them.
  • Validation of input parameters. All input data is validated to ensure that it will not corrupt the database. It is of course still the developer's responsibility to ensure that it will not cause problems for the customer in question.
  • Database access.
  • Any billing required. For example, if a customer calls a SOAP function to create a telephone, the function will add a transaction and update the customer's balance for the telephone creation fee.
  • Any other required side effects, such as updating telephone provisioning files.

Data flow

For the Apache based SOAP server, the data flow is as follows:

  • Apache receives a SOAP request at http://<website>/api/soap/, where http://<website>/ is the main website for Enswitch. HTTPS may be used if the web server has this configured. The namespace is "Integrics/Enswitch/API".
  • It uses Perl's SOAP::Lite module to parse the SOAP request.
  • SOAP::Lite then invokes the appropriate function from one of the files in /opt/enswitch/current/lib/API/*.pm. It is not necessary for those using the SOAP API to understand these files, but they can be of interest to those who wish to understand what the functions do behind the scenes.
  • These files return data to SOAP::Lite.
  • The SOAP data that SOAP::Lite produces can be hard to interpret in some SOAP clients such as .NET, so the web code at /api/soap/ does some post-processing of the XML to simplify this.
  • Apache returns the data to the SOAP.

Functions

The functions available closely follow the Enswitch database schema. Typically, each table would have the following functions:

  • get_<object>(): Gets the data about a specific database row. For example, get_phone() returns data for a specific telephone. The input parameters are typically an authentication user, an authentication password, and a unique identifier for the object required.
  • get_<object>s(): Gets an array of database rows. For example, get_phones() returns data for all the telephones in the user's customer. The input parameters are typically an authentication user, an authentication password, and optionally a filter to only return rows matching specific criteria.
  • save_<object>(): If the object already exists, updates it. If not, creates a new object. For example, save_phone() either creates a new telephone or updates an existing one. The input parameters are typically an authentication user, an authentication password, a unique identifier for the object to update (usually "0" for a new object), and all the fields to set for this object. The list of fields varies with the type of object (see the WSDL for more details), and usually all fields must be set and in the order listed in the WSDL.
  • delete_<object>(): Deletes the object. For example, delete_phone() will delete a telephone. The input parameters are typically an authentication user, an authentication password, and a unique identifier for the object to be deleted. Where appropriate, the function will also delete any data dependant on the object. For example, delete_phone() also deletes any non-shared speed dials belonging to the telephone. If not all dependant data can safely be deleted, the SOAP function will return an error and nothing will be deleted.

Some tables have additional functions. Please see the WSDL for more details.

The Enswitch web interface and SOAP

By default, the Enswitch web interface invokes the functions in /opt/enswitch/current/lib/API/*.pm directly. Alternatively, it can be configured to invoke them via the SOAP Server. This can be useful to developers, as the SOAP requests can be captured using tcpdump, ngrep, wireshark, or similar, to inspect what data is being sent. If you wish to do this, please contact your vendor.

It can also be useful to read the files under /opt/enswitch/current/www, which provide examples of how to invoke each function. Any function call starting with "api::" is a call to the API functions.

WSDL

WSDL is available for commonly used functions. To generate it, run this command on any machine running the Enswitch web server:

  • enswitch wsdl

Copyright © Integrics Ltd., all rights reserved. Permission is granted for Enswitch partners, customers, and their resellers to copy the contents of this page into their own documentation and redistribute this to their customers.