Dialogic PowerMedia XMS RESTful API User guide

Category
Software
Type
User guide
Dialogic® PowerMedia XMS RESTful API
User's Guide
November 2022
05-2703-018
www.dialogic.com
2
Copyright and Legal Notice
Copyright © 2022 Enghouse Systems Limited (“Enghouse”). All Rights Reserved. You may not reproduce this
document in whole or in part without permission in writing from Enghouse at the address provided below.
All contents of this document are furnished for informational use only and are subject to change without notice and
do not represent a commitment on the part of Enghouse and its affiliates or subsidiaries ("Enghouse"). Reasonable
effort is made to ensure the accuracy of the information contained in the document. However, Enghouse does not
warrant the accuracy of this information and cannot accept responsibility for errors, inaccuracies or omissions that
may be contained in this document.
INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH DIALOGIC® PRODUCTS. NO LICENSE,
EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY
THIS DOCUMENT. EXCEPT AS PROVIDED IN A SIGNED AGREEMENT BETWEEN YOU AND ENGHOUSE, ENGHOUSE
ASSUMES NO LIABILITY WHATSOEVER, AND ENGHOUSE DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY,
RELATING TO SALE AND/OR USE OF ENGHOUSE PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO
FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY INTELLECTUAL PROPERTY
RIGHT OF A THIRD PARTY.
Enghouse products are not intended for use in certain safety-affecting situations.
Due to differing national regulations and approval requirements, certain Enghouse products may be suitable for use
only in specific countries, and thus may not function properly in other countries. You are responsible for ensuring
that your use of such products occurs only in the countries where such use is suitable. For information on specific
products, contact Enghouse at legal.operations@enghouse.com
It is possible that the use or implementation of any one of the concepts, applications, or ideas described in this
document, in marketing collateral produced by or on web pages maintained by Enghouse may infringe one or more
patents or other intellectual property rights owned by third parties. Enghouse does not provide any intellectual
property licenses with the sale of Enghouse products other than a license to use such product in accordance with
intellectual property owned or validly licensed by Enghouse and no such licenses are provided except pursuant to a
signed agreement with Enghouse. More detailed information about such intellectual property is available from
Enghouse's legal department at 80 Tiverton Court, Suite 800 Markham, Ontario L3R 0G4.
Enghouse encourages all users of its products to procure all necessary intellectual property licenses required to
implement any concepts or applications and does not condone or encourage any intellectual property infringement
and disclaims any responsibility related thereto. These intellectual property licenses may differ from country to
country and it is the responsibility of those who develop the concepts or applications to be aware of and comply with
different national license requirements.
Dialogic, Dialogic Pro, DialogicOne, Dialogic Buzz, Brooktrout, BorderNet, PowerMedia, PowerVille, PowerNova,
ControlSwitch, I-Gate, Veraz, Cantata, TruFax, and NMS Communications, among others as well as related logos,
are either registered trademarks or trademarks of Enghouse and its affiliates or subsidiaries. Enghouse's trademarks
may be used publicly only with permission from Enghouse. Such permission may only be granted by Enghouse legal
department at 80 Tiverton Court, Suite 800 Markham, Ontario L3R 0G4. Any authorized use of Enghouse's
trademarks will be subject to full respect of the trademark guidelines published by Enghouse from time to time and
any use of Enghouse's trademarks requires proper acknowledgement.
The names of actual companies and products mentioned herein are the trademarks of their respective owners.
This document discusses one or more open source products, systems and/or releases. Enghouse is not responsible
for your decision to use open source in connection with Enghouse products (including without limitation those
referred to herein), nor is Enghouse responsible for any present or future effects such usage might have, including
without limitation effects on your products, your business, or your intellectual property rights.
3
Table of Contents
1. Welcome ....................................................................................................... 15
2. Overview ....................................................................................................... 16
RESTful API Description ..................................................................................... 17
Client Side Technologies ................................................................................. 17
RESTful API with HTTP Methods .......................................................................... 18
RESTful API Request/Response Model ............................................................... 18
XML Schema Definition ................................................................................... 19
Event Streaming ............................................................................................ 20
Event notification using Webhooks ................................................................... 22
Response Codes ............................................................................................. 22
3. Resource-Based Element Introduction .......................................................... 25
Applications and Application IDs (appid) ........................................................... 25
Time Values................................................................................................... 25
4. API Resources ............................................................................................... 26
5. List of Available Resources ............................................................................ 28
Call Resource .................................................................................................... 28
calls ............................................................................................................. 29
HTTP GET ...................................................................................................... 29
HTTP POST .................................................................................................... 29
Call Concepts ................................................................................................. 37
Call Sub-Resource ............................................................................................. 39
call ............................................................................................................... 39
HTTP GET ...................................................................................................... 39
HTTP PUT ...................................................................................................... 39
HTTP DELETE ............................................................................................... 109
Conference Resource ....................................................................................... 109
conferences ................................................................................................. 109
HTTP GET .................................................................................................... 109
HTTP POST .................................................................................................. 110
Conference Concepts .................................................................................... 117
Conference Sub-Resource ................................................................................ 118
conference .................................................................................................. 118
HTTP GET .................................................................................................... 118
HTTP PUT .................................................................................................... 118
HTTP DELETE ............................................................................................... 146
Event Handler Resource ................................................................................... 146
RESTful Event Streaming Data Format Change ................................................ 146
eventhandlers .............................................................................................. 146
HTTP GET .................................................................................................... 148
HTTP POST .................................................................................................. 148
Event Handler Sub-Resource ............................................................................ 149
eventhandler ............................................................................................... 149
HTTP GET .................................................................................................... 149
HTTP PUT .................................................................................................... 151
HTTP DELETE ............................................................................................... 153
Events ........................................................................................................... 153
keepalive .................................................................................................... 153
Call Events .................................................................................................. 161
4
MRCP Events ............................................................................................... 171
Conference Events ....................................................................................... 174
MRB Events ................................................................................................. 175
MRCP Resource ............................................................................................... 175
mrcps ......................................................................................................... 176
HTTP GET .................................................................................................... 176
HTTP POST .................................................................................................. 176
MRCP Sub-Resource ........................................................................................ 177
mrcp .......................................................................................................... 177
HTTP GET .................................................................................................... 177
HTTP PUT .................................................................................................... 177
HTTP DELETE ............................................................................................... 184
6. XML Schema Definition of Elements ............................................................ 185
7. Text and Image Overlays ............................................................................ 186
8. XMSTool RESTful Utility ............................................................................... 194
9. Appendix A: Media File Formats .................................................................. 195
Play ............................................................................................................ 195
Record ........................................................................................................ 196
10. Appendix B: Feature Details ........................................................................ 199
Use Case for Dialogic Proprietary Header Tags in a SIP/WebRTC INVITE ................ 199
Enhanced Video Conference Layout Sizing .......................................................... 200
Create a Conference ..................................................................................... 200
Update the Conference to Crop Mode .............................................................. 201
Update the Conference to Fit Mode ................................................................. 201
WebM Container .............................................................................................. 201
Record Audio and Video ................................................................................ 201
Play Back the Audio and Video Stream ............................................................ 202
Joining Separate Audio and Video Streams ......................................................... 202
Create the Audio Conference ......................................................................... 203
Join Video Streams ....................................................................................... 203
Join the Audio Streams to the Conference ....................................................... 203
Record One of the Parties .............................................................................. 204
Automatic Deletion of Silence Recordings ........................................................... 204
Encryption Record ........................................................................................... 205
Multi-Stream SFU Video Conferencing with the XMS RESTful API ........................... 205
Overview of Application Steps ........................................................................ 207
Application Responsibility and Considerations .................................................. 208
Client/Browser Settings and Considerations ..................................................... 209
Limitations, Behaviors, and Known Issues ....................................................... 209
Example Call Flow (3 Party SFU Video Conference) ........................................... 211
5
Revision History
Revision
Release Date
Notes
05-2703-018
November 2022
Updates to support PowerMedia XMS Release 5.1
Removed MP4 container as a supported file format,
removed Dialogic proprietary aud and vid formats.
Updates for support of webhooks for event
notification.
05-2703-017
(Updated)
October 2021
Updates to document support of Selective
Forwarding Unit (SFU) conferencing including the
addition of the Multi-Stream SFU Video Conferencing
with the XMS RESTful API section.
05-2703-016
(Updated)
October 2020
end_playcollect: Added “max_digits” as a reason
value.
05-2703-016
(Updated)
April 2020
Transfer: Updated section.
05-2703-016
January 2020
Updates to support PowerMedia XMS Release 4.1.
Call Resource: Updated the HTTP POST section.
Call Sub-Resource: Updated the Accept/Answer
Incoming Call and Modify Call Attributes sections.
Event Handler Resource: Updated the eventhandlers
section.
Event Handler Sub-Resource: Updated the
eventhandler section.
Events: Updated the media_started section in Media
Events. Added the fax_info and end_fax sections in
Media Events.
XML Schema Definition of Elements: Updated the
section.
05-2703-015
(Updated)
December 2019
Call Resource: Updated the HTTP POST section.
Conference Resource: Updated the HTTP POST
section.
05-2703-015
(Updated)
August 2019
Events: Updated the streaming section in Call Events.
05-2703-015
(Updated)
June 2019
Events: Removed the fax_info and end_fax sections in
Media Events.
05-2703-015
March 2019
Updates to support PowerMedia XMS Release 4.0.
6
Revision
Release Date
Notes
Global change: Removed references to Dialogic
proprietary .vid and .aud file formats.
Call Sub-Resource: Updated the
recording_audio_mime_params
and add_party/update_party
sections.
Conference Resource: Updated the HTTP POST
section.
Conference Sub-Resource: Updated the HTTP PUT
section.
XML Schema Definition of Elements: Updated the
section.
Appendix A: Media File Formats: Updated the Video
(Record) section.
05-2703-014
(Updated)
February 2019
Response Codes: Updated the section.
Call Sub-Resource: Updated the
recording_audio_mime_params
and add_party/update_party
sections.
Conference Resource: Updated the HTTP POST
section.
Conference Sub-Resource: Updated the HTTP PUT
section.
Events: Updated the media_started, end_play,
end_playcollect, end_record, end_playrecord,
end_overlay, end_send_message, end_dtmf,
end_event, fax_info, and end_fax sections in Media
Events.
XML Schema Definition of Elements: Updated the
section.
05-2703-014
(Updated)
January 2019
Call Sub-Resource: Updated the Accept/Answer
Incoming Call, recording_video_mime_params,
record, playrecord, and hangup sections.
Conference Sub-Resource: Updated the record and
playrecord sections.
Events: Updated end_play, end_playcollect, and
end_playrecord sections in Media Events.
05-2703-014
(Updated)
May 2018
Call Sub-Resource: Updated the
recording_video_mime_params section.
05-2703-014
(Updated)
January 2018
Call Sub-Resource: Updated the multi_record section.
Conference Sub-Resource: Updated the multi_record
section.
7
Revision
Release Date
Notes
05-2703-014
October 2017
Updates to support PowerMedia XMS Release 3.5.
RESTful API with HTTP Methods: Updated the
Response Codes section.
Call Resource: Updated the HTTP POST section.
Call Sub-Resource: Updated the Accept/Answer
Incoming Call, record_track, record, multi_record,
update_multi_record, playrecord, and dial sections.
Conference Resource: Updated the HTTP POST
section.
Conference Sub-Resource: Updated the Modify
Conference Attributes, record, multi_record,
update_multi_record, and playrecord sections.
Events: Updated the end_record and end_playrecord
sections and added the MRB Events section.
Appendix A: Media File Formats: Updated the audio
play and audio record tables.
Appendix B: Feature Details: Added the section and
reorganized the features.
Encryption Record: Added the section.
05-2703-013
(Updated)
June 2017
Call Resource: Updated the Media File Locations
section in Call Concepts.
Call Sub-Resource: Updated the
play_source_attributes,
recording_audio_mime_params,
recording_video_mime_params, and multi_record
sections.
Appendix A: Media File Formats: Updated the play and
record tables.
Automatic Deletion of Silence Recordings: Added the
section.
05-2703-013
May 2017
Updates to support PowerMedia XMS Release 3.3.
Updated the document for Call Progress Analysis (cpa)
profile and operation and Global Unique Session
Identifier (gusid) support.
RESTful API with HTTP Methods: Added the Response
Codes section.
05-2703-012
(Updated)
March 2017
Call Resource: Added the hangup_ack_mode
parameter in calls.
Call Sub-Resource: Added the hangup_ack_mode
parameter in Accept/Answer Incoming Call, added the
audio_track_id parameter in play_source_attributes,
added the Multitrack Play examples, added the
primary_video_source parameter in
8
Revision
Release Date
Notes
add_party/update_party, and updated the
transaction_id parameter in stop.
Conference Sub-Resource: Added the
primary_video_source parameter in Modify
Conference Attributes.
05-2703-012
November 2016
Updates to support PowerMedia XMS Release 3.2.
Updated the document for WebM support.
Call Sub-Resource: Updated the recording_video_type
values.
Conference Resource: Added the mixing_mode
parameter to support SFU and updated the layout
parameter.
Conference Sub-Resource: Updated the
recording_video_type values.
Appendix A: Media File Formats: Updated the Audio
Record - MKV, Audio Record - WebM, Video Record -
MKV, and Video Record - WebM tables.
Enhanced Video Conference Layout Sizing: Added the
section.
WebM Container: Added the section.
Joining Separate Audio and Video Streams: Added the
section.
05-2703-011
(Updated)
July 2016
Call Sub-Resource: Updated add_party/update_party,
remove_party, and join/union to support multiple
joins.
05-2703-011
(Updated)
May 2016
Call Sub-Resource and Video Record: Added how to
use the input video stream's resolution and framerate
as the target encoding resolution and framerate.
05-2703-011
(Updated)
April 2016
Overview: Updated the RESTful API Request/
Response Model section to state that the request and
response payloads are encoded to UTF-8.
05-2703-011
March 2016
Updated the values for recording_audio_type.
Call Sub-Resource:
Updated the record examples and added a
note to show how to record audio and video on
a single file.
05-2703-011
March 2016
Updates to support PowerMedia XMS Release 3.1.
Call Resource:
Added a note about the URI parameters for
play, record, and playrecord.
9
Revision
Release Date
Notes
Added rtcp_feedback to the Request Payload
Attributes table.
Call Sub-Resource:
Added rtcp_feedback to the Request Payload
Attributes table.
Appendix A: Media File Formats:
Added MKV and MP4 Video Play and Video
Record capabilities.
Updated the Video Record - Dialogic VID table
and the Video Record - 3GP table.
Use Case for Dialogic Proprietary Header Tags in a
SIP/WebRTC INVITE:
Added the section.
05-2703-010
(Updated)
October 2015
Call Sub-Resource:
Added video/3gpp to the video_type
parameter of play_source_attributes.
Updated recording_video_type values.
Conference Sub-Resource:
Updated recording_video_type values.
05-2703-010
October 2015
Updates to support PowerMedia XMS Release 3.0.
RESTful API Description:
Updated information to include HTTPS.
API Resources:
Updated the all resource base URL to include
HTTPS.
Call Resource:
Updated the Request Payload Attributes table
in the HTTP Post section.
Call Sub-Resource:
Updated the Request Payload Attributes tables
in the HTTP PUT section.
Updated the play_source_attributes,
recording_audio_mime_params,
recording_video_mime_params, and
content_element_attributes tables in the HTTP
PUT section.
Removed overlay from the HTTP PUT section.
Added send_event to the HTTP PUT section.
Updated the join/unjoin Request Payload
Attributes table in the HTTP PUT section.
10
Revision
Release Date
Notes
Updated the send_info/send_info_ack Request
Payload Attributes table in the HTTP PUT
section.
Added send_prack/send_prack_ack/
send_answer_ack to the HTTP PUT section.
Added dial to the HTTP PUT section.
Updated the get_call_info Response Payload
Attributes table in the HTTP PUT section.
Conference Resource:
Updated layout_regions and region_overlays in
the Request Payload Attributes table in the
HTTP Post section.
Conference Sub-Resource:
Updated layout_regions and region_overlays in
the Modify Conference Attributes in the HTTP
PUT section.
Added playcollect, playrecord, send_dtmf, and
send_event to the HTTP PUT section.
Updated the update_play Request Payload
Attributes table in the HTTP PUT section.
Events:
Added start_play and end_event to Media
Events.
Updated ringing in Call Events.
Added info and info_ack sections in Call
Events.
XML Schema Definition of Elements:
Updated the XML definition of elements.
Dynamic Text and Image Generation:
Removed section.
Text and Image Overlays:
Added section.
Appendix A: Media File Formats:
Updated the media file formats.
11
Revision
Release Date
Notes
05-2703-009
(Updated)
June 2015
Call Resource:
Added local_rtp_address and headers to the
Request Payload Attributes table for HTTP
POST.
Call Sub-Resource:
Added local_rtp_address to the Request
Payload Attributes table for HTTP PUT.
05-2703-009
(Updated)
April 2015
Call Resource:
Added audio, video, message, setup,
content_type, and content to the Request
Payload Attributes table for HTTP POST.
Call Sub-Resource:
Updated send_message section.
Appendix A: Media File Formats:
Updated the Video Play - Dialogic VID
(proprietary) table in Media File Formats
section to correct RESTful attribute format for
jpeg codec.
05-2703-009
February 2015
Updates to support PowerMedia XMS Release 2.4.
Call Sub-Resource:
Updated send_info/send_info_ack section to
change content_data to content.
05-2703-008
January 2015
Updates to all the resource response payload example
sections for IPv6 support.
Call Sub-Resource:
Added note to mode parameter in
add_party/update_party section.
Conference Resource:
Updated the value auto to automatic for
layout_size parameter.
Conference Sub-Resource:
Updated the value auto to automatic for
layout_size parameter.
Event Handler Resource:
Added RESTful Event Streaming Data Format
Change section.
Events:
Updated end_play, end_playcollect,
end_record, and end_playrecord sections in
Media Events.
12
Revision
Release Date
Notes
Updated end_recognize section in MRCP
Events.
Updated sections to change call_id to id in
MRCP Events.
Appendix A: Media File Formats:
Updated the Video Record table in Media File
Formats section.
05-2703-007
October 2014
Updates to support PowerMedia XMS Release 2.3.
Call Sub-Resource:
Added add_ice_candidate, send_hangup_ack,
and send_message sections.
Added msg_payload attributes,
msg_payload_content attribute, and
msg_payload_uri attributes tables.
Added content_element parameter to
send_message section and added
content_element_attributes table.
Added get_last_action and get_last_event
sections.
Conference Sub-Resource:
Added get_last_action and get_last_event
sections.
MRCP Sub-Resource:
Added get_last_action and get_last_event
sections.
Event Handler Resource:
Added speech_marker value to type
parameter.
Event Handler Sub-Resource:
Added speech_marker value to type
parameter.
Events:
Added end_send_message section in Media
Events.
Updated end_play, end_playcollect, and
end_record sections in Media Events.
Added message, alarm, stream, prack,
accepted, and answered sections in Call
Events.
Updated dtmf and tone sections in Call Events.
Added speech_marker section in MRCP Events.
13
Revision
Release Date
Notes
Added conf_overlay_expired section in
Conference Events.
XML Schema Definition of Elements:
Added updated schema definition.
Appendix A: Media File Formats:
Added new section.
05-2703-006
May 2014
Updates to dtmf event in Call Events section.
05-2703-005
April 2014
Updates to support PowerMedia XMS Release 2.2.
05-2703-004
October 2013
Updates to support PowerMedia XMS Release 2.1.
Global change:
Renamed this document from Developer's
Guide to User's Guide.
Reorganized the resource-based elements and
payload attributes tables.
XML Schema Definition of Elements:
Added updated schema definition.
05-2703-003
January 2013
Updates to support PowerMedia XMS Release 2.0.
Call Resource:
Updated http post/put request payload, single
call instance response payload, call_action,
add_party, and update_party in XML Schema
Definitions for Call.
Added new clamp_dtmf, auto_gain_control,
echo_cancellation, digits, interval, level,
content_type, and content to the
<call_action> Parameters table.
Added new send_dtmf, send_info,
send_info_ack, transfer, redirect, and hangup
to the <call_action> Parameters table.
Added new display_name, accept,
early_media, and info_ack_mode to the <call>
Element Attributes table.
Added new section for <call> Element
Attribute Notes.
Conference Resource:
Added new playrecord conference action in
XML Schema Definition for Conference.
14
Revision
Release Date
Notes
Added new barge, cleardigits, beep, and
recording_uri to the <conf_action>
Parameters table.
XML Schema Definition of Elements:
Added updated schema definition.
05-2703-002
July 2012
Updated to support PowerMedia XMS Release 1.1.
This includes adding additional information to all
sections and reorganizing the layout of the Resource
sections.
Global change:
Renamed PowerMedia XMS RESTful web
service to PowerMedia XMS RESTful server.
Call Resource:
Added new interdigit_timeout parameter to
the <call_action> Parameters table.
Conference Resource:
Added new region parameter to the
<conf_action> Parameters table.
XML Schema Definition of Elements:
Added updated schema definition.
Dynamic Text and Image Generation:
Added new section.
XMSTool RESTful Utility:
Added new section.
05-2703-001
February 2012
Initial release of this document.
Refer to www.dialogic.com for product updates and for information about support policies,
warranty information, and service offerings.
15
1. Welcome
This User's Guide provides information about the Dialogic® PowerMedia Extended Media
Server (also referred to herein as "PowerMedia XMS" or "XMS") RESTful API interface,
including available features and resource-based component definitions.
The PowerMedia XMS RESTful API is one of several APIs that can be used to drive the
PowerMedia XMS.
16
2. Overview
This section provides information about the PowerMedia XMS RESTful API interface,
including available features and resource-based component definitions.
The PowerMedia XMS RESTful API is one of several APIs that can be used to drive the
PowerMedia XMS. The architectural diagram below shows how the RESTful interface fits into
PowerMedia XMS.
Two web servers are used in PowerMedia XMS:
Apache (httpd) server
Controls a web-based interface for operations, administration and maintenance.
lighttpd server
Processes call control and media commands delivered via the RESTful API as
described in this guide. The lighttpd server includes a Fast Common Gateway
Interface (FCGI) process, which allows efficient interfacing between PowerMedia XMS
processes.
The PowerMedia XMS translates RESTful commands into the PowerMedia HMP media
engine's low-level API. The media engine itself handles SIP calls, plays/records multimedia,
and mixes multimedia conferences.
PowerMedia XMS provides two call control models:
First party call control (1PCC)
The application sends commands to the PowerMedia XMS to establish SIP or WebRTC
calls on the application's behalf. In this model, the application does not need to be
involved in making or receiving SIP calls and related SDP negotiation.
Third party call control (3PCC)
The application handles SIP calls or WebRTC signaling and SDP negotiation, and the
PowerMedia XMS only performs media processing operations.
17
RESTful API Description
The PowerMedia XMS RESTful API uses a Representational State Transfer (RESTful) web
service. This web service is a software system designed to support interoperable machine-
to-machine interactions over a network, using the HTTP or HTTPS protocol. For more
information on using HTTPS, refer to API Resources for port and authentication information.
The RESTful API consists of a series of requests and responses built around the transfer of
representations of "resources". These resources are accessed through Universal Resource
Indicators (URIs).
RESTful client-server architecture is where clients initiate requests to servers and servers
process the requests and return appropriate responses.
In a RESTful application, the http client is the application which contains the business logic
and PowerMedia XMS is the http server which handles the client request and processes the
media commands.
Client Side Technologies
The "client side" refers to the client that communicates with the PowerMedia XMS and
directs the session with the caller. Essentially, any language or operating system may be
used to build a client. The main requirement is that the client supports HTTP and XML.
Listed below are some possible examples of client-side development platforms that can be
used to command PowerMedia XMS services. Comments are included on multithreading,
which is important for the event handler.
Java This object-oriented, operating system-independent programming environment
is fully multithreaded. Several XSD/XML parsers are available, as well as HTTP client
class libraries. See the XML Schema Definition section for information on XSDs.
Python This operating system-independent interpreted scripting language has POSIX
threading available. HTTP protocol client library and Python XML/Schema processing
tool are also available.
.NET This Integral Microsoft Windows component supports the building and running
of applications and XML web services. HTTP module and XSD schema definition tools
are available.
Ruby This open source scripting language contains a multiprocessing model that
may be needed for the event handler. An HTTP client API and XSD validation tools are
available.
C/C++ These general purpose programming languages are fully
multithreaded. cURL library (http://curl.haxx.se) is used for HTTP processing and
Xerces C++ XML parser (http://xerces.apache.org/xerces-c) is used for XML. For a
proof of concept, see
http://www.dialogic.com/support/helpweb/helpweb.aspx/3584/powermedia_xms_rest
ful_C_Sharp_demo/PM_XMS.
18
RESTful API with HTTP Methods
In the RESTful API, the four HTTP methods are translated to the actions shown in the
following table.
HTTP Method
Request
Response
POST
Create a new resource
Contents of a newly
created resource
PUT
Modify an existing resource
Contents of an updated
resource
GET
Retrieve information for all
instances of a specific resource
type, or information regarding a
specific resource
Contents of resource
information
DELETE
Delete an existing resource
N/A
RESTful API Request/Response Model
The HTTP request/response model is the mechanism by which media control functionality is
invoked. A RESTful HTTP request is sent to the PowerMedia XMS. The HTTP response carries
the resulting response code of the operation, as well as a response body if it applies to the
specific operation. The payload type used for the message body is XML. The request and
response payloads are encoded to UTF-8.
All Call Resources
If a client wished to retrieve a list of all call resources currently active on the PowerMedia
XMS, it would issue an HTTP GET request. The HTTP GET request would be sent on the web
service with the IP address of the PowerMedia XMS <server>. For example:
http://<server>/default/calls?appid=app
If successful, the response code to the HTTP GET would be 200 OK. The response body
would resemble the following example:
<web_service version="1.0">
<calls_response size="2">
<call_response appid="master"
identifier="123zdasdkz"
href=/default/calls/123zdasdkz
cpa = "yes"
signaling = "yes"
source_uri=sip:[email protected]
call_type="inbound" />
<call_response
identifier="178zdasdkz"
href=/default/calls/178zdasdkz
cpa = "no"
signaling = "no"
sdp=[sdp]
call_type="3pcc" />
</calls_response>
</web_service>
The above example shows a client requesting information for all calls with a response of two
active identifiers along with the attributes of each call resource.
19
Single Call Resource
If a client wanted to retrieve information for only a single specific call resource, it would
invoke the following HTTP GET request. The specific call identifier is part of the GET URL.
http://<server>/default/calls/1279697438?appid=app
If successful, the response code to the HTTP GET would be 200 OK. The response body
would be as follows:
<web_service version="1.0">
<call_response appid="master"
identifier="1279697438"
href=/default/calls/1279697438
cpa = "yes"
signaling = "yes"
source_uri=sip:[email protected]
call_type="inbound">
</calls_response>
</web_service>
Additional request/response examples are contained within Resource-Based Components.
All XML sent to the PowerMedia XMS should have proper XML escape codes within string
content. For example, when a <call> contains SDP info in the sdp="" attribute, newlines
need to be converted to the proper XML escape code "&#xA;" and "&#xD".
<call sdp="v=0&#xA;o=sipclient 1376422095 1376422096 IN IP4
10.20.129.100&#xA;s=sipclient&#xA;c=IN IP4 10.20.129.100&#xA;t=0
0&#xA;m=audio 49162 RTP/AVP &#xA;a=rtpmap:0 pcmu/8000&#xA;a=sendrecv&#xA;" media="audiovideo"
signaling="no"/>
XML Schema Definition
PowerMedia XMS uses an XML schema definition (also referred to herein as "XSD"). The
XSD formally describes the structure, content, and semantics of the XML payload for the
PowerMedia XMS RESTful API call and media commands.
An XSD may be used to generate client-side code, allowing contents of XML documents to
be treated as objects. The generated code usually enforces type-checking, thus supporting
client-side validation of the XML payload before it is sent to the PowerMedia XMS.
Definitions of individual elements are referenced throughout this guide. The full XSD is
provided in XML Schema Definition of Elements.
PowerMedia XMS RESTful API is designed using the following XML Schema declarations:
Element
An element describes the data it contains. It consists of a name and data type. When an
element definition contains additional elements or attributes, it is a complex type.
<xs:element name="call_response">
Attribute
An attribute is a simple type definition that cannot contain other elements. Attribute names
are always within quotation marks.
<xs:attribute name="media">
Sequence
Specifies the order in which attributes or elements within a complex type must be listed.
<xs:element name="call_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="call_action" minOccurs="0" />
</xs:sequence>
<xs:attribute name="signaling" type="boolean_type" />
<xs:attribute name="media" type="media_type" />
20
Complex Type
Defines an element containing other elements and attributes or mixed content (elements
and text).
<xs:element name="call_response">
<xs:complexType>
<xs:sequence>
<xs:element ref="call_action" minOccurs="0" />
</xs:sequence>
<xs:attribute name="signaling" type="boolean_type" />
<xs:attribute name="destination_uri" type="xs:string" />
<xs:attribute name="source_uri" type="xs:string" />
<xs:attribute name="call_type" type="call_type_option" />
<xs:attribute name="sdp" type="xs:string" />
<xs:attribute name="cpa" type="boolean_type" />
<xs:attribute name="media" type="media_type" />
<xs:attribute name="dtmf_mode" type="dtmf_mode_option" />
<xs:attribute name="async_dtmf" type="boolean_type" />
<xs:attribute name="async_tone" type="boolean_type" />
<xs:attribute name="cleardigits" type="boolean_type" />
<xs:attributeGroup ref="response_attrgroup" />
</xs:complexType>
</xs:element>
Simple Type
Creates a constrained data type for an element or attribute value.
<xs:simpleType name="call_type_option">
<xs:restriction base="xs:string">
<xs:enumeration value="inbound" />
<xs:enumeration value="outbound" />
<xs:enumeration value="3pcc" />
</xs:restriction>
</xs:simpleType>
Refer to the specific resource-based element sections for more information.
Event Streaming
While most RESTful applications fit well into the HTTP request/response model, telephony
applications must be able to handle unsolicited events such as digit detection and play
completion. This concept is called Comet or HTTP event streaming. In a normal HTTP
interaction, the client sends a request to the server, which processes it and sends the HTTP
response. The connection between the client and server is then closed. This process will
take place continuously as long as the web service is running; however, with HTTP
event/data streaming, a reliable TCP connection remains open after the response is sent
from the server, allowing the server to continue to send raw data to the client without
solicitation or without client request.
For PowerMedia XMS, HTTP event streaming is implemented in the eventhandler
resource. When the client wishes to receive asynchronous events, it uses an HTTP POST to
create an eventhandler and subscribe to specific event types. The client then performs an
HTTP GET on the newly created eventhandler and the PowerMedia XMS RESTful API
responds with a 200 OK; however, the TCP connection remains open. Any event data related
to resources and event types are pushed to the client until the Eventhandler is deleted by
the client.
  • Page 1 1
  • Page 2 2
  • Page 3 3
  • Page 4 4
  • Page 5 5
  • Page 6 6
  • Page 7 7
  • Page 8 8
  • Page 9 9
  • Page 10 10
  • Page 11 11
  • Page 12 12
  • Page 13 13
  • Page 14 14
  • Page 15 15
  • Page 16 16
  • Page 17 17
  • Page 18 18
  • Page 19 19
  • Page 20 20
  • Page 21 21
  • Page 22 22
  • Page 23 23
  • Page 24 24
  • Page 25 25
  • Page 26 26
  • Page 27 27
  • Page 28 28
  • Page 29 29
  • Page 30 30
  • Page 31 31
  • Page 32 32
  • Page 33 33
  • Page 34 34
  • Page 35 35
  • Page 36 36
  • Page 37 37
  • Page 38 38
  • Page 39 39
  • Page 40 40
  • Page 41 41
  • Page 42 42
  • Page 43 43
  • Page 44 44
  • Page 45 45
  • Page 46 46
  • Page 47 47
  • Page 48 48
  • Page 49 49
  • Page 50 50
  • Page 51 51
  • Page 52 52
  • Page 53 53
  • Page 54 54
  • Page 55 55
  • Page 56 56
  • Page 57 57
  • Page 58 58
  • Page 59 59
  • Page 60 60
  • Page 61 61
  • Page 62 62
  • Page 63 63
  • Page 64 64
  • Page 65 65
  • Page 66 66
  • Page 67 67
  • Page 68 68
  • Page 69 69
  • Page 70 70
  • Page 71 71
  • Page 72 72
  • Page 73 73
  • Page 74 74
  • Page 75 75
  • Page 76 76
  • Page 77 77
  • Page 78 78
  • Page 79 79
  • Page 80 80
  • Page 81 81
  • Page 82 82
  • Page 83 83
  • Page 84 84
  • Page 85 85
  • Page 86 86
  • Page 87 87
  • Page 88 88
  • Page 89 89
  • Page 90 90
  • Page 91 91
  • Page 92 92
  • Page 93 93
  • Page 94 94
  • Page 95 95
  • Page 96 96
  • Page 97 97
  • Page 98 98
  • Page 99 99
  • Page 100 100
  • Page 101 101
  • Page 102 102
  • Page 103 103
  • Page 104 104
  • Page 105 105
  • Page 106 106
  • Page 107 107
  • Page 108 108
  • Page 109 109
  • Page 110 110
  • Page 111 111
  • Page 112 112
  • Page 113 113
  • Page 114 114
  • Page 115 115
  • Page 116 116
  • Page 117 117
  • Page 118 118
  • Page 119 119
  • Page 120 120
  • Page 121 121
  • Page 122 122
  • Page 123 123
  • Page 124 124
  • Page 125 125
  • Page 126 126
  • Page 127 127
  • Page 128 128
  • Page 129 129
  • Page 130 130
  • Page 131 131
  • Page 132 132
  • Page 133 133
  • Page 134 134
  • Page 135 135
  • Page 136 136
  • Page 137 137
  • Page 138 138
  • Page 139 139
  • Page 140 140
  • Page 141 141
  • Page 142 142
  • Page 143 143
  • Page 144 144
  • Page 145 145
  • Page 146 146
  • Page 147 147
  • Page 148 148
  • Page 149 149
  • Page 150 150
  • Page 151 151
  • Page 152 152
  • Page 153 153
  • Page 154 154
  • Page 155 155
  • Page 156 156
  • Page 157 157
  • Page 158 158
  • Page 159 159
  • Page 160 160
  • Page 161 161
  • Page 162 162
  • Page 163 163
  • Page 164 164
  • Page 165 165
  • Page 166 166
  • Page 167 167
  • Page 168 168
  • Page 169 169
  • Page 170 170
  • Page 171 171
  • Page 172 172
  • Page 173 173
  • Page 174 174
  • Page 175 175
  • Page 176 176
  • Page 177 177
  • Page 178 178
  • Page 179 179
  • Page 180 180
  • Page 181 181
  • Page 182 182
  • Page 183 183
  • Page 184 184
  • Page 185 185
  • Page 186 186
  • Page 187 187
  • Page 188 188
  • Page 189 189
  • Page 190 190
  • Page 191 191
  • Page 192 192
  • Page 193 193
  • Page 194 194
  • Page 195 195
  • Page 196 196
  • Page 197 197
  • Page 198 198
  • Page 199 199
  • Page 200 200
  • Page 201 201
  • Page 202 202
  • Page 203 203
  • Page 204 204
  • Page 205 205
  • Page 206 206
  • Page 207 207
  • Page 208 208
  • Page 209 209
  • Page 210 210
  • Page 211 211
  • Page 212 212
  • Page 213 213
  • Page 214 214
  • Page 215 215
  • Page 216 216
  • Page 217 217

Dialogic PowerMedia XMS RESTful API User guide

Category
Software
Type
User guide

Ask a question and I''ll find the answer in the document

Finding information in a document is now easier with AI