This chapter describes the operations in the Third Party Call interface of the RESTful facade provided in Oracle Communications Services Gatekeeper.
Applications use the RESTful Third Party Call interface in Services Gatekeeper to set up a call, get information on that call, cancel the call request before it is successfully completed, or end a call that has been successfully set up.
Additionally, applications use this interface to specify the data required for the billing operation associated with the call.
When the Administration Server for your Services Gatekeeper domain is in the running state, the REST service descriptions of these operations can be found at:
http://host:port/rest/third_party_call/index.html
Where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The RESTful Third Party Call interface includes these operations:
To set up a call between two parties (referred to as the calling party and the called party), provide the SIP-formatted URI of the calling party and the called party in the body of the request for the call. Optionally, the request can also indicate any cost-charging parameters to be applied to the call.
If the call setup is successful, the response header will contain the URI of the newly created resource as the value of the Location header field. Additionally, the response body will contain the call identifier for the newly created call object. Use this call identifier to reference the call later.
http://host:port/rest/third_party_call/calls
where host and port are the host name and port of the system on which Services Gatekeeper is installed.
The request body for the POST request accepts the following parameters:
calledParty: String. Required. The address (URI) of the party to whom the call is made. Specified as sip:user_name@destination_ip:destination_port.
callingParty: String. Required. The address (URI) of the party making the call. Specified as sip:user_name@origin_ip:origin_port.
charging: a JSON object. Optional. This object defines the cost charging parameters for the call. A call with no charging parameters can be entered as "charging": null.
If a charge is to be applied, provide values for the following in the charging object:
description: String. Required if the charging object is present in the body of the request. The text to be used for information and billing.
amount: Number (integer, or decimal). Optional. The amount to be charged.
code: String. Optional. The charging code, from an existing contractual description.
currency: String. Optional. The currency identifier as defined in ISO 4217 [9].
The request body for this operation is represented by the following JSON data structure, where the value part of each name/value pair indicates its data type:
{
"calledParty": "URI",
"callingParty": "URI",
"charging": {
"description": "String",
"amount": "BigDecimal",
"code": "String",
"currency": "String"
}
}
The value in the Location header field is a single absolute URI in the following format:
http://host:port/rest/third_party_call/{${result}
where result is a string-formatted call identifier for the newly-created call. See Example 5-2.
If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
The response body for the POST request contains the call identifier returned in the Location header field. The call identifier is the value for the result term in the response body represented by the following name/value pair structure:
{"result": "String"}
See Example 5-2.
Example 5-1 HTTP POST Request to Set Up a Call
POST /rest/third_party_call/calls HTTP/1.1
X-Session-ID: app: -1780934689905632396
Authorization: Basic ZG9tY1uX3VzZXI6ZG9tYWluX3VzZXI=
X-Param-Keys:
X-Param-Values:
User-Agent: Jakarta Commons-HttpClient/3.0
Host: localhost:8001
Content-Length: 105
Content-Type: application/json
{"calledParty":"sip:alice@sipcalled_host:port",
"charging":
{
"description":"testing",
"amount":"11",
"code":"1111",
"currency":"rmb"
},
"callingParty":"sip:bob@sipcalling_host:port"
}
Example 5-2 HTTP POST Response to Setting Up a Call
HTTP:/1.1 201 Created
Date: Wed, 20 Oct 2010 06:58:06 GMT
Location: http://local:host:8001/rest/third_party
_call/call/app-1q39oi07wpvjl|e9674e8214447c1663a016d434c@sipcalling
_host|-50d94925ab34bf0
Content-Length: 96
Content-Type: application/json
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
X-Powered-By: Servlet/2.5 JSP/2.1
{"result":"app-1q39oi07wpvjl|e9674e8214447c1663a016d434c@sipcalling
_host|-50d94925ab34bf0"}
The Get Call Information operation retrieves the information on a previously-established call.
To retrieve the information on a previously-established call, provide the appropriate call identifier in the HTTP GET request. This call identifier should have been obtained by the set up request for the call as the value for result in the response received for the HTTP POST request to set up the call. See Example 5-2.
If the operation is successful, the response body will contain the time the call started and the current status of the call. Additionally, if the call was terminated, the response body will indicate the total duration of the call and the reason for its termination.
http://host:port/rest/third_party_call/call/${callIdentifier}
where:
host and port are the host name and port of the system on which Services Gatekeeper is installed.
callIdentifier is the call identifier obtained from the response to the POST request to set up the call.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
When the GET request is successful, the response body contains the appropriate values for the following parameters that describe the call:
callStatus: String. The current status of the call as one of the following values:
CallInitial: The call is being established.
CallConnected: The call is active.
CallTerminated: The call was terminated.
duration: Integer. The duration of the call in seconds. Present in the response body when callStatus is CallTerminated.
startTime: String. The start time for the call in the ISO 8601 extended format, yyyy-mm-ddThh-mm-ss.
terminationCause: String. The reason for the termination of the call. Present in the response body only when callStatus is CallTerminated. Its value can be one of the following:
CallAborted
CalledPartyBusy
CalledPartyNoAnswer
CalledPartyNotReachable
CallHangUp
CallingPartyBusy
CallingPartyNoAnswer
CallingPartyNotReachable
The parameter values are placed in a data structure as the value for result in the following JSON structure, where the value part of each name/value pair indicates its data type:
{"result": {
"callStatus": "CallInitial|CallConnected|CallTerminated",
"duration": "Integer",
"startTime": "Calendar",
"terminationCause":"CallingPartyNoAnswer|CalledPartyNoAnswer|CallingPartyBusy|C
alledPartyBusy|CallingPartyNotReachable|CalledPartyNotReachable|CallHangUp|CallA
borted"
}}
GET /rest/third_party _call/call/app-1q39oi07wpvjl|e9674e8214447c1663a016d434c@sipcalling _host|-50d94925ab34bf0 HTTP/1.1 X-Session-ID: app: -123456789012346789 Authorization: Basic ZG9tY1uX3VzZXI6ZG9tYWluX3VzZXI= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host: localhost:8001
HTTP:/1.1 201 Created
Date: Wed, 20 Oct 2010 06:58:06 GMT
Content-Length: 124
Content-Type: application/json
X-Plugin-Param-Keys:
X-Plugin-Param-Values:
X-Powered-By: Servlet/2.5 JSP/2.1
{"result":
{"startTime":"2010-10-20T4:58:18.254+08:00",
"terminationCause":null,
"duration":"0",
"callStatus":"CallConnected"
}
}
The Cancel Call operation cancels a previously-requested call that is in its initial state and not yet active. This operation will have no effect if the call is already established.
To cancel a call before it is established, provide the appropriate call identifier in the Request-URI for the POST method. This identifier should have been obtained by the initial setup request for the call.
There is no request or response body for the POST request to cancel a call. If the request fails, the body of the error response will contain the call identifier and the type of exception.
http://host:port/rest/third_party_call/cancel-call/${callIdentifier}
where:
host and port are the host name and port of the system on which Services Gatekeeper is installed.
callIdentifier is the call identifier obtained from the response to the HTTP POST reqest to set up the call.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
Example 5-5 HTTP POST Request to Cancel a Call
The POST command to cancel the call contains the required call identifier.
POST /rest/third_party _call/cancel-call/app-1q39oi07wpvjl|e9674e8214447c1663a016d434c@sipcalling _host|-50d94925ab34bf0 HTTP/1.1 X-Session-ID: app: -123456789012346789 Authorization: Basic ZG9tY1uX3VzZXI6ZG9tYWluX3VzZXI= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host: localhost:8001 Content-length: 0
Example 5-6 Response for the HTTP POST Request to Cancel a Call
If the request to cancel the call succeeds, you will see a response similar to the following:
HTTP:/1.1 204 No Content Date: Wed, 20 Oct 2010 07:48:14 GMT Content-Length: 0 X-Plugin-Param-Keys: X-Plugin-Param-Values: X-Powered-By: Servlet/2.5 JSP/2.1
Example 5-7 Error Response Example
If the request to cancel the call fails, you will see an error response similar to the following. The error body will contain the call identifier as the value for the correlator attribute.
HTTP:/1.1 500 Internal Server Error
Date: Wed, 20 Oct 2010 07:48:26 GMT
Content-Length: 261
Content-Type: application/json
X-Powered-By: Servlet/2.5 JSP/2.1
{"error" :
{"message":"Invalid input value for message part Could not find a plugin for
this message: correlator:
app-1q39oi07wpvjl|e9674e8214447c1663a016d434c@sipcalling
_host|-50d94925ab34bf0",
"type":"org.csapi.schema.parlayx.common.v2_1.ServiceException"
}
}
The End Call operation ends a call that is active.
To end a call, provide the appropriate call identifier in the Request-URI for this operation. This identifier should have been obtained by the initial setup request for the call.
There is no request or response body for this operation. If the request fails, the body of the error response will contain the call identifier and the type of exception.
http://host:port/rest/third_party_call/end-call/${callIdentifier}
where:
host and port are the host name and port of the system on which Services Gatekeeper is installed.
${callIdentifier} is the call identifier obtained from the response to the Make Call request.
Standard header fields. If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Understanding RESTful Errors and Exceptions".
POST /rest/third_party_call/end-call/app-1q39oi07wpvjl| e9674e8214447c1663a016d434c@sipcalling_host|-50d94925ab34bf0 HTTP/1.1 X-Session-ID: app: -123456789012346789 Authorization: Basic ZG9tY1uX3VzZXI6ZG9tYWluX3VzZXI= X-Param-Keys: X-Param-Values: User-Agent: Jakarta Commons-HttpClient/3.0 Host: localhost:8001 Content-length: 0