Child pages
  • Overview of sipXcom/Unite APIs

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

This is a technical manual describing the APIs used by the OpenUC sipXcom and Unite software. It contains information for developers and system administrators on installing, managing and developing for the OpenUC softwaresipXcom and Unite software (referred to as Unite).

About

...

APIs

At the heart of the eZuce openUC Communications Platform are is our extensive collection of Web Service APIs. By exposing the power of the platform through APIs customers can customize their users' communications experience within their organization.

Because openUC the system can act as a go-between for aging systems and new customer applications, sipXcom APIs acts as a link to assist communication or integration that allows developers to build a single application that interacts with many different systems. In support of this functionality, several different web service protocols and authentication schemes are available.

openUC is sipXcom and Unite are built with a variety of software languages a number of embedded open source applications. For more information, see the eZuce openUC Third-Party Component List.

  1. Benefits of using Web APIs

  • Integration with other systems. For example, integration with a given company's internal user management system.

  • Integration with other applications. For example, Microsoft Outlook© toolbar add-ons.

  • Internally inside openUC sipXcom and Unite when two services on potentially two different servers to communicate with each other.

  1. What are openUC Unite Web APIs

openUC Unite utilizes SOAP and REST API’s. SipXconfig exposes web services and allows clients to connect and to manage, communicate and diagnose data. REST and SOAP are two methods of exposing web services.

...

RESTlet is the framework used by sipXconfig Unite for exposing RESTful API. For exposing SOAP API, eZuce utilities Apache Axis framework.

Earlier in the system development of openUC/sipXcom sipXconfig Unite, the sipXconfig service (the configuration service) started by providing SOAP web services but as REST technology evolved it was eventually adopted and further SOAP development has been put on hold.

REST APIs

About REST APIs

REST (an acronym for “REpresentational State Transfer”) represents a new approach to systems architecture and a lightweight alternative to web services.

eZuce Inc provides a RESTful interface through which you can retrieve information about an instance and make configuration changes. Using the REST interface’s simple HTTP calls, you can configure openUC and ReachUnite. Requests on resources are implemented with the standard HTTP methods:

  • GET to read;

  • PUT to create;

  • POST to update;

  • DELETE to delete.

The sipXcom Unite REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

Base URL

The base URL for the Configuration API is the following: https://host.example.com/sipxconfig/rest

Using REST Services

Here is an example of how to print the content of a phonebook named Sales to standard output in CSV format:

...

<withVoicemail>false</withVoicemail>

</call-sequence>

SOAP APIs

About SOAP APIs

The SOAP API for sipXconfig lets you perform many operations offered by sipXconfig in a programmatic way and without interacting with the sipXconfig Web user interface. The sipXconfig API is continuously extended and offers most of the functionality available in the web interface.

Base URL

The base URL for the Configuration API is the following:

https://<host>/sipxconfig/services

Using SOAP Services

Benefits of using SOAP APIs:

  • You can integrate the sipXcom functionality with your company's IT infrastructure (intranet).  

  • You can automate or script processes such as: adding or importing users, updating phones, assigning phones to groups and others.

  • You can customize the sipXconfig User Interface (UI) and to suit your needs.

You can use SOAP with WSDL, which is a formal API definition, and generate bindings in your preffered preferred programming language (Python, Perl, Ruby, Java, and others).  It is recommended to select a programming language with good SOAP client support.

Resources for building SOAP web-based service clients

Every sipXconfig Unite installation already publishes the SOAP API on URLs https://yourdomain/sipxconfig/services/*Service.

Ruby

From the WSDL, you can use the SOAP4R project to build client bindings.

...

   http://sipXcom.sipfoundry.org/rep/sipXcom/main/sipXconfig/web/src/org/sipfoundry/sipxconfig/api/sipxconfig.wsdl


OpenFire APIs

Openfire is a cross-platform real-time collaboration server based on the XMPP (Jabber) protocol. For more information, see http://www.igniterealtime.org/.

Using sipXcom Web API

 Areas of extensibility

 The available group web service APIs have been categorized according to their usage:

 


To do this...

Use this API...

Configure the system, users, devices and features.

  1. Manage

Control communications in the system.

  1. Communicate

Retrieve  information about the system.

  1. Diagnose


Supported languages

The sipXcom Web APIs support development written in any language that supports SOAP and REST. For example: JSON, XML, C++, Java, Ruby, Standard ANSI and others.

...

Compilers and software required

You can write using any standard word processing application and compile your programs using Visual C++, Visual Studio,  .Net, Unix C, Unix C++, C# compilers.

HTTP response status codes

The following table lists the generic HTTP response status codes for the GET (retrieve), POST (create), PUT (modify), and DELETE (remove) methods of the sipXcom APIs:



 

Response Code

HTTP Request

Description

200 OK

GET, PUT, DELETE

Request successful

400 Bad Request

GET, POST, PUT, DELETE

Bad query

401 Unauthorized

GET, POST, PUT, DELETE

Request requires user authentication

403 Forbidden

GET, POST, PUT, DELETE

Authentication failure

404 Not Found

GET, POST, PUT, DELETE

Resource not found

408 Request Timeout

GET, POST, PUT, DELETE

Request has timed out

500 Server Error

GET, POST, PUT, DELETE

Internal server error

502 Bad Gateway

GET, POST, PUT, DELETE

Data store failure

 

...


Adding new services

sipXconfig is implemented using the Restlet Framework API to add RESTful services. For more information on the Restlet Framework API, see http://www.restlet.org.

Note: The RESTlet API version used by siXecs requires HTTP PUT request must have a body. You can add space, or anything to the body to work around it.

Service design

Follow these seps to design your REST service,  prior to service implementation:

  • Identify resources and design the resource structure

  • Determine which operations (GET, PUT, POST, DELETE) will be available for which resources

  • Map resources into URI structure

  • Determine representation for each resource (specific format XML/JSON)

Service implementation

Follow these steps to implementa implement a web service:

  • Implement resources.

Each resource is an instance of RESTlet resource class. Every RESTful function is mapped into one or more Resource methods. For example, GET method is implemented by Resource.represent

...