Representational State Transfer (REST) APIs in CEA

REST APIs in CEA

We can use the Communications Enabled Applications (CEA) feature to integrate either web telephony or web collaboration into applications using a Representational State Transfer (REST) API. REST is a network architecture that defines how resources on the Internet are accessed. REST is not a standard, but uses common Internet standards such as HTTP and HTML.

REST API overview

The following tables show the REST APIs and commands used in CEA, including a generic list of each aspect of the requests and responses. Also see the information on accessing telephony and data sharing browser sessions using REST APIs.

HTTP Method and URI Description
PUT /collaborationSession Enable collaboration
GET /collaborationSession; <encodedSession> Get collaboration status
GET /collaborationSession; <encodedPeerAddressOfRecord> Start a collaboration session with a peer
DELETE /collaborationSession; <encodedSession> End a collaboration session
POST /collaborationSession/data; <encodedSession> Send data to the collaboration peer
GET /event; <encodedSession> Retrieve event data (call status, collaboration status, collaboration data)
PUT /call Make a call
GET /call; <encodedSession> Get status on an active call
DELETE /call; <encodedSession> End a call
PUT /callNotification Register for call notification
GET /callNotification; <encodedSession> Get call notification information
DELETE /callNotification; <encodedSession> Unregister for call notification

URI parameters

URI parameters are used by the REST API. These parameters are located after the path portion of the request URI; for example:
http://host:port/commsvc.rest/CommServlet/collaborationSession?JSON=true&addressOfRecord=tel:987654321

and their descriptions.
Parameter Applicable HTTP Method and URI Description
JSON All Optional parameter that we can use on any REST request. When the JSON parameter is detected and set to true, the REST response is formatted as JSON; otherwise XML. The presence of this parameter does not affect the format of the request.
addressOfRecord PUT /collaborationSession Optional parameter when enabling collaboration. It allows the specified value to be used as an identifier of the session. This identifier gets exposed to other users of collaboration. If absent, a random identifier is created. Whether specified or not, the identifier is returned in the response as the collaborationId.
peerAddressOfRecord GET /collaborationSession Required parameter when starting a collaboration session with a peer. It represents the identifier of the peer to which a collaboration must be established. This identifier is the collaborationId that was returned to the peer when the peer enabled collaboration.
returnAllEvents GET /event; <encodedSession> Optional parameter used to get new events. If set to true, all available events are returned. Otherwise, only the next single event is returned. If this parameter is not used, the default is to return a single event.
ceaVersion All Required parameter used to declare the version of the client sending the request. It is used to support backward compatibility.
replaceRequest GET /event; <encodedSession> Optional parameter used to force a new GET /event request to replace an outstanding GET /event request. The outstanding request gets a 304 error response.

Request fields

With some REST APIs, additional information is provided in the body of the HTTP message, which must be formatted as either XML or JSON. The following table explains those request fields. Some fields are specific to web telephony or web collaboration while others apply to both. As another reference, see the schema that describes the REST requests and response format. It is called CommServletSchema.xsd and can be found in the WAS installation directory under /etc/cea/schema.

and their descriptions.
Request fields Applicable HTTP Method and URI Description
addressOfRecord
PUT /call
PUT /callNotification
Required when making a call or registering for call notification. It represents the address of record of the phone making the call, or the phone registering for call notification. Common to all address of record references in this REST API, the values can be either SIP or TEL URIs.
peerAddressOfRecord PUT /call This field is required when making a call. It represents the address of record of the phone to be called.
collaborationData POST /event; <encodedSession> This field is required when sending data to a collaboration peer. It represents the data being sent.
enableCollaboration
PUT /call
PUT /callNotification
Optional when either making a call or registering for call notification. It allows collaboration to be enabled at the same time.
peerDeviceControlled PUT /call By default, PUT /call causes the device associated with the addressOfRecord to be controlled and originate the call. When peerDeviceControlled is set to true, the device associated with the peerAddressOfRecord is controlled and originates the call.

Response fields

The response to the REST API is described in the following table. As with the request fields, some response fields are specific to web telephony or web collaboration, while others apply to both. Many of the response fields include URIs that can be used in follow on REST requests. They are encoded to ensure that subsequent requests, related to the originally passed in address of record, remain associated with the same session. As another reference, see the schema that describes the REST requests and response format. It is called CommServletSchema.xsd and can be found in the WAS installation directory under /etc/cea/schema.

response fields and their descriptions.
Response field Applicable HTTP Method and URI Description
infoMsg All Message indicating the results of the requested operation.
returnCode All Number that represents the result of the requested operation. For example, when a request operation completes successfully, the response is 200. This full list of return codes can be seen in the REST interface schema. See table 5 for a complete list.
eventList
GET /event
Array of events (web collaboration data available, web collaboration status or call status changes) used in response to GET /event. Each event has three fields: type, data, and infoMsg. The different types include call status, collaboration status and collaboration data. The data is dependent on the event type, but is similar to the REST response fields of callStatus and collaborationStatus, or the data sent with POST /event. The infoMsg is additional information about the event. The following is a JSON formatted eventList:
[{"type":2, "data":
  "information from peer", "infoMsg": "Successfully
   fetched data"}] 
Possible event types based on their enum values include:
0: Data Event
1: Call Status Event
2: Web Collab Status Event
3: Failover Event
eventUri All except GET /event This encoded URI is returned from multiple REST APIs. It can be used to post new data in a collaboration session or to poll an event, such as a change in call status, change in collaboration status, or new data becoming available in a collaboration session. It doesn't return immediately. It will wait for an event to occur before a response is sent, or when a configured amount of time transpires. We can configure the time from the console and is called the Maximum hold time.
callerAddressOfRecord All including /call or /callNotification in the URI Address of record for the calling phone.
calleeAddressOfRecord All including /call or /callNotification in the URI Address of record for the phone that was called.
callServiceUri All including /call or /callNotification in the URI Encoded URI is returned from the make a call request, used for getting status on, or ending a call.
callNotifyUri All except GET /event This encoded URI is returned from registering for call notification, used for monitoring a phone to see if a call has arrived or to unregister call notification.
callId All including /call or /callNotification in the URI when a call is active Call ID associated with the current active call.
callFailureReason GET /call Upon a failed call, this is a message indicating the reason for the failure.
callStatus GET /call Represents the status of the call (initiated, established, failed, cleared).
collaborationStatus All except GET /event Represents the status of a web collaboration session. Valid states are as follows: ESTABLISHED, NOT_ESTABLISHED, STARTING, and READY.
collaborationServiceUri All except GET /event when collaboration is enabled This encoded URI is returned from the enable collaboration request, used for getting status or ending a web collaboration session.
collaborationId All except GET /event when collaboration is enabled Unique identifier of a user collaboration session. If an optional address of record is provided when enabling collaboration, then the collaborationId matches that value.
forPeerCollaborationUri All except GET /event when collaboration is enabled URI that a user can send to a peer. The peer uses it to establish a web collaboration session. It includes the peerAddressOfRecord parameter.
peerCollaborationUri All except GET /event when collaboration is enabled and the peer in the collaboration session has been found This encoded URI can be used to establish a web collaboration with the other user on the phone call.
ceaVersion All This string represents the version of the server.
Return codes

The following table lists the possible return codes seen in the REST response returnCode field.

codes and their descriptions.
Code number Description
200 Similar to an HTTP 200 OK. No problems were detected.
201 Response to the GET /event request if no new events are found. This return does not imply an error because an event might not have been generated.
300 REST request was invalid. For example, the HTTP method and URI did not match what is supported by the API.
301 REST request was a follow-on request, such as getting call or collaboration status, but no existing session information was found.
302 An error occurred when trying to parse the REST request. An error exists in the format of the JSON or XML provided.
303 For telephony-related REST requests, a user name was not found in the credentials. This would only happen if the configuration indicates that the user name associated with a caller should be retrieved from the request credentials.
304 Response to an outstanding GET /event request if, before a response is sent, a redundant GET /event request is received.
305 REST request is missing required parameters or fields. For example, this return results if the API makes a call sent without providing an addressOfRecord identifying the caller.
306 An unexpected error occurred.
307 A telephony related REST request was made that did not locate a call.
308 A collaboration-related REST request was made, but collaboration was not enabled for in the session.

Sample REST requests and responses

Enable collaboration with JSON
   REST Request:        PUT http://host:port/commsvc.rest/CommServlet/collaborationSession?JSON=true&ceaVersion=1.0.0.1
    REST Response:        {
      "returnCode":200, "infoMsg":"Successfully enabled collaboration", "collaborationId":"local.1242138965934_1", "callNotifyUri":"CommServlet/callerNotification;ibmappid=local.1242138965934_1", "collaborationStatus":"NOT_ESTABLISHED", "collaborationServiceUri":"CommServlet/collaborationSession;ibmappid=local.1242138965934_1", "forPeerCollaborationUri":"CommServlet/collaborationSession?addressOfRecord=local.1242138965934_1", "eventUri":"CommServlet/event;ibmappid=local.1242138965934_1"
      "ceaVersion":"1.0.0.1"
      }
Enable collaboration with XML
   REST Request:        PUT http://host:port/commsvc.rest/CommServlet/collaborationSession?ceaVersion=1.0.0.1
    REST Response:        <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
      <CommRestResponse xmlns="http://jaxb.servlet.commsvc.ws.ibm.com/">
         <returnCode>200</returnCode>
         <infoMsg>Successfully enabled collaboration</infoMsg>
         <callNotifyUri>CommServlet/callerNotification;ibmappid=local.1242140626552_1</callNotifyUri>
         <collaborationId>local.1242140626552_1</collaborationId>
         <collaborationStatus>NOT_ESTABLISHED</collaborationStatus>
         <collaborationServiceUri>CommServlet/collaborationSession;ibmappid=local.1242140626552_1</collaborationServiceUri>
         <forPeerCollaborationUri>CommServlet/collaborationSession?addressOfRecord=local.1242140626552_1</forPeerCollaborationUri>
         <eventUri>CommServlet/event;ibmappid=local.1242140626552_1</eventUri>
         <ceaVersion>1.0.0.1</ceaVersion>
      </CommRestResponse>  
Making a call with JSON
  REST Request
      PUT http://host:port/commsvc.rest/CommServlet/call?JSON=true&ceaVersion=1.0.0.1
      {
      "enableCollaboration": false, "addressOfRecord":"sip:phone1@192.168.1.100", "peerAddressOfRecord":"sip:phone2@192.168.1.100"
      }
    REST Response:        {
      "returnCode":200, "infoMsg":"Call attempted between sip:phone1@192.168.1.100 and sip:phone2@192.168.1.100.", "callerAddressOfRecord":"sip:phone1@192.168.1.100", "calleeAddressOfRecord":"sip:phone2@192.168.1.100", "callServiceUri":"CommServlet/call;ibmappid=local.1242140626552_42", "callNotifyUri":"CommServlet/callerNotification;ibmappid=local.1242140626552_42", "collaborationStatus":"NOT_ESTABLISHED", "eventUri":"CommServlet/event;ibmappid=local.1242140626552_42"
      "ceaVersion":"1.0.0.1"
      }
Making a call with XML
   REST Request
       PUT http://host:port/commsvc.rest/CommServlet/call?ceaVersion=1.0.0.1
       <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
       <CommRestRequest xmlns="http://jaxb.servlet.commsvc.ws.ibm.com/">
          <addressOfRecord>sip:phone1@192.168.1.100</addressOfRecord>
          <peerAddressOfRecord>sip:phone2@192.168.1.100</peerAddressOfRecord>
          <enableCollaboration>true</enableCollaboration>
       </CommRestRequest>
             REST Response
       <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
       <CommRestResponse xmlns="http://jaxb.servlet.commsvc.ws.ibm.com/">
          <returnCode>200</returnCode>
          <infoMsg>Call attempted between sip:phone1@192.168.1.100 and sip:phone2@192.168.1.100.</infoMsg>
          <callerAddressOfRecord>sip:phone1@192.168.1.100</callerAddressOfRecord>
          <calleeAddressOfRecord>sip:phone2@192.168.1.100</calleeAddressOfRecord>
          <callServiceUri>CommServlet/call;ibmappid=local.1242140626552_33</callServiceUri>
          <callNotifyUri>CommServlet/callerNotification;ibmappid=local.1242140626552_33</callNotifyUri>
          <collaborationStatus>NOT_ESTABLISHED</collaborationStatus>
          <eventUri>CommServlet/event;ibmappid=local.1242140626552_33</eventUri>
          <ceaVersion>1.0.0.1</ceaVersion>
       </CommRestResponse>
Related information:

Representational State Transfer

HTTP Method and URI	Description
PUT /collaborationSession	Enable collaboration
GET /collaborationSession; <encodedSession>	Get collaboration status
GET /collaborationSession; <encodedPeerAddressOfRecord>	Start a collaboration session with a peer
DELETE /collaborationSession; <encodedSession>	End a collaboration session
POST /collaborationSession/data; <encodedSession>	Send data to the collaboration peer
GET /event; <encodedSession>	Retrieve event data (call status, collaboration status, collaboration data)
PUT /call	Make a call
GET /call; <encodedSession>	Get status on an active call
DELETE /call; <encodedSession>	End a call
PUT /callNotification	Register for call notification
GET /callNotification; <encodedSession>	Get call notification information
DELETE /callNotification; <encodedSession>	Unregister for call notification

Parameter	Applicable HTTP Method and URI	Description
JSON	All	Optional parameter that we can use on any REST request. When the JSON parameter is detected and set to true, the REST response is formatted as JSON; otherwise XML. The presence of this parameter does not affect the format of the request.
addressOfRecord	PUT /collaborationSession	Optional parameter when enabling collaboration. It allows the specified value to be used as an identifier of the session. This identifier gets exposed to other users of collaboration. If absent, a random identifier is created. Whether specified or not, the identifier is returned in the response as the collaborationId.
peerAddressOfRecord	GET /collaborationSession	Required parameter when starting a collaboration session with a peer. It represents the identifier of the peer to which a collaboration must be established. This identifier is the collaborationId that was returned to the peer when the peer enabled collaboration.
returnAllEvents	GET /event; <encodedSession>	Optional parameter used to get new events. If set to true, all available events are returned. Otherwise, only the next single event is returned. If this parameter is not used, the default is to return a single event.
ceaVersion	All	Required parameter used to declare the version of the client sending the request. It is used to support backward compatibility.
replaceRequest	GET /event; <encodedSession>	Optional parameter used to force a new GET /event request to replace an outstanding GET /event request. The outstanding request gets a 304 error response.

Request fields	Applicable HTTP Method and URI	Description
addressOfRecord	PUT /call PUT /callNotification	Required when making a call or registering for call notification. It represents the address of record of the phone making the call, or the phone registering for call notification. Common to all address of record references in this REST API, the values can be either SIP or TEL URIs.
peerAddressOfRecord	PUT /call	This field is required when making a call. It represents the address of record of the phone to be called.
collaborationData	POST /event; <encodedSession>	This field is required when sending data to a collaboration peer. It represents the data being sent.
enableCollaboration	PUT /call PUT /callNotification	Optional when either making a call or registering for call notification. It allows collaboration to be enabled at the same time.
peerDeviceControlled	PUT /call	By default, PUT /call causes the device associated with the addressOfRecord to be controlled and originate the call. When peerDeviceControlled is set to true, the device associated with the peerAddressOfRecord is controlled and originates the call.

Response field	Applicable HTTP Method and URI	Description
infoMsg	All	Message indicating the results of the requested operation.
returnCode	All	Number that represents the result of the requested operation. For example, when a request operation completes successfully, the response is 200. This full list of return codes can be seen in the REST interface schema. See table 5 for a complete list.
eventList	GET /event	Array of events (web collaboration data available, web collaboration status or call status changes) used in response to GET /event. Each event has three fields: type, data, and infoMsg. The different types include call status, collaboration status and collaboration data. The data is dependent on the event type, but is similar to the REST response fields of callStatus and collaborationStatus, or the data sent with POST /event. The infoMsg is additional information about the event. The following is a JSON formatted eventList: [{"type":2, "data": "information from peer", "infoMsg": "Successfully fetched data"}] Possible event types based on their enum values include: 0: Data Event 1: Call Status Event 2: Web Collab Status Event 3: Failover Event
eventUri	All except GET /event	This encoded URI is returned from multiple REST APIs. It can be used to post new data in a collaboration session or to poll an event, such as a change in call status, change in collaboration status, or new data becoming available in a collaboration session. It doesn't return immediately. It will wait for an event to occur before a response is sent, or when a configured amount of time transpires. We can configure the time from the console and is called the Maximum hold time.
callerAddressOfRecord	All including /call or /callNotification in the URI	Address of record for the calling phone.
calleeAddressOfRecord	All including /call or /callNotification in the URI	Address of record for the phone that was called.
callServiceUri	All including /call or /callNotification in the URI	Encoded URI is returned from the make a call request, used for getting status on, or ending a call.
callNotifyUri	All except GET /event	This encoded URI is returned from registering for call notification, used for monitoring a phone to see if a call has arrived or to unregister call notification.
callId	All including /call or /callNotification in the URI when a call is active	Call ID associated with the current active call.
callFailureReason	GET /call	Upon a failed call, this is a message indicating the reason for the failure.
callStatus	GET /call	Represents the status of the call (initiated, established, failed, cleared).
collaborationStatus	All except GET /event	Represents the status of a web collaboration session. Valid states are as follows: ESTABLISHED, NOT_ESTABLISHED, STARTING, and READY.
collaborationServiceUri	All except GET /event when collaboration is enabled	This encoded URI is returned from the enable collaboration request, used for getting status or ending a web collaboration session.
collaborationId	All except GET /event when collaboration is enabled	Unique identifier of a user collaboration session. If an optional address of record is provided when enabling collaboration, then the collaborationId matches that value.
forPeerCollaborationUri	All except GET /event when collaboration is enabled	URI that a user can send to a peer. The peer uses it to establish a web collaboration session. It includes the peerAddressOfRecord parameter.
peerCollaborationUri	All except GET /event when collaboration is enabled and the peer in the collaboration session has been found	This encoded URI can be used to establish a web collaboration with the other user on the phone call.
ceaVersion	All	This string represents the version of the server.

Code number	Description
200	Similar to an HTTP 200 OK. No problems were detected.
201	Response to the GET /event request if no new events are found. This return does not imply an error because an event might not have been generated.
300	REST request was invalid. For example, the HTTP method and URI did not match what is supported by the API.
301	REST request was a follow-on request, such as getting call or collaboration status, but no existing session information was found.
302	An error occurred when trying to parse the REST request. An error exists in the format of the JSON or XML provided.
303	For telephony-related REST requests, a user name was not found in the credentials. This would only happen if the configuration indicates that the user name associated with a caller should be retrieved from the request credentials.
304	Response to an outstanding GET /event request if, before a response is sent, a redundant GET /event request is received.
305	REST request is missing required parameters or fields. For example, this return results if the API makes a call sent without providing an addressOfRecord identifying the caller.
306	An unexpected error occurred.
307	A telephony related REST request was made that did not locate a call.
308	A collaboration-related REST request was made, but collaboration was not enabled for in the session.