Existing Services
...
General URL structure
Common prefix:
| Panel | |||||
|---|---|---|---|---|---|
|
Testing the services
Here is an example of how to print the content of a phonebook named sales to stdout in CSV format
| Panel |
|---|
curl --insecure --basic -u superadmin [https://]{host}:8443/sipxconfig/rest/phonebook/sales |
...
To test the call placing service with curl use:
| Panel |
|---|
curl --insecure -X PUT [https://]{user}:{password}@{host}:8443/sipxconfig/rest/call/{number} |
HTTP PUT to service URL will cause sipXconfig to place call to {number}.
The calls is placed using authorized user credentials. It works in the same way as click-to-call available on the user portal. User's phone rings first and, once someone answers, it places the call to {number}.
Version|4.2
New Services
General URL structure
Common prefix:
| Panel | |||||
|---|---|---|---|---|---|
|
Note: how to see inside the SSL with Wireshark is described here SipX_ConfigServer_Troubleshooting#Using_Wireshark_to_see_inside_the_boxTo test the call forwarding service with curl use:
| Panel |
|---|
curl --insecure -X PUT [https://]{user}:{password}@{host}/sipxconfig/rest/my/forward/ --data-binary @{file.xml} |
HTTP PUT to service URL will cause sipXconfig to place a callforward to a number with specs in the xml file.
A xml file should look like:
| Panel |
|---|
<call-sequence> |
HTTP GET to service URL will return the saved callforwarding scheme. In addition, a new field is added: <withVoicemail>
The value of this field is true if the user voicemail permission is set to true, false if voicemail permission is set to false
| Panel |
|---|
<call-sequence> |
Admin services
Accessible for users with admin priviledgesprivileges:
...
URI | Methods | Formats |
|---|---|---|
/phonebook |
...
GET | Returns a list with all the phonebooks. XML: {{<?xml version="1.0" encoding="UTF-8"?> | |
/phonebook/{name} |
...
GET | Returns a list with {name} phonebook entries. CSV | |
/phone | POST | Creates a phone. XML |
/auto-attendant | GET | |
/auto-attendant/specialmode |
...
GET | GET retrieves the use the special auto attendant status(true/false). PUT will set it to true, DELETE will set it to false. XML, JSON | |
/auto-attendant/ |
...
{attendant}/special | PUT | PUT - Use the attendant as special attendant; DELETE - TBD |
| /activecdrs/{user} | GET | GET - Retrieve active calls for given user, sample output <cdrs> |
User services
Accessible for all users:
URI | Methods | Formats |
|---|---|---|
/my/call/{to} | PUT | Initiates the call from the user to {to} address.PUT method requires non empty body which is ignored.Supported as GET for clients that do not handle PUT. |
/my/voicemail/pin/{pin} | PUT | changes user voicemail PIN |
/my/forward | GET | retrieves (GET) or changes (PUT) user call forwardingXML,JSON |
/my/feed/voicemail/{folder} | GET | voicemail folder presented as RSS feed |
/my/phonebook | GET | JSON, XMLphonebook representation |
/my/phonebook/entry/{entryId} | GET | retrieves (GET), changes (PUT) and deletes (DELETE) entries in private phonebookXMLJSON |
/my/contact-information | GET | |
/my/search/phonebook?query={search-term} | GET | searching user phonebookXML |
/my/mailbox/{user}/preferences/activegreeting | GET | retrieves and sets active greeting setting for a specific user |
...
sipXconfig used the RESTlet API to add RESTful services
| Panel |
|---|
Please note, due to a bug in RESTlet, it requires HTTP PUT request must have a body. You can add space, or anything to the body
to workaround it.
Service design
- Identify resouces 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
- 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
- :Resource instances are managed by Spring. You can inject any context or manager that is necessary to perform service operations. For example phonebook service delegates bulk of the work to PhonebookManager.
- Write unit test for resource and representation
- :Use mock objects to verify if injected managers' are used in expected way (for example does _POST really calls _save'' method with expected parameters?).
- :For resources verify XML/JSON representation generation and parsing.
- Implement representations
- :sipXconfig services intended to be used pragmatically should at the minimum support XML and JSON representations. Read-only services marshal sipXconfig domain objects into representation.
...
/my/conferences | GET | returns a list with all conferences for a specific user |
/my/activecdrs | GET | returns a list with all active calls (ongoing) for a specific user in XML or JSON format |
/my/logindetails | GET | returns username and im ID for a specific user in XML or JSON format. To be used when alias is provided in authentication details |
Sample php Click to Call Code:
| Code Block |
|---|
<?php
$to="101"; //Number to dial
$from="5001"; //userid in sipx
$pass="1234"; //sipx pin (NOT SIP password)
//replace sipx.gcgov.local with your sipx server
$url = "http://sipx.gcgov.local:6667/callcontroller/".$from."/".$to."?isForwardingAllowed=true";
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_USERPWD, $from.":".$pass);
$result = curl_exec($ch);
curl_close($ch);
?>
|
Future Services
User ('my') services (those are services needed to implement functionality available through current user portal)
...
If you are thinking about implementing an external application interacting with sipXecs and you need a new service ask on the sipx-dev list.