Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide Release 5.1 E37533-01 |
|
|
PDF · Mobi · ePub |
This chapter describes the operations in the Third Party Call interface of the RESTful Web Services 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 calls.
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 machine on which Services Gatekeeper is installed.
The Make Call operation sets up a call between two parties referred to as the calling party and the called party.
To set up a call, provide the SIP-formatted URI of the calling party and the called party in the body of the request for the Make Call operation. Optionally, the request can also indicate any cost-charging parameters to be applied to the call.
If the Make Call operation 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 for later.
http://host:port/rest/third_party_call/calls
where host and port are the host name and port of the machine on which Services Gatekeeper is installed.
The request body for the Make Call operation accepts the following parameters:
calledParty. String. Required. The address (URI) of the party to whom the call is made. Specified as sip:
uname@
destination_ip:
destination_port.
callingParty. String. Required. The address (URI) of the party making the call. Specified as sip:
uname@
origin_ip:
origin_port.
charging. a JSON object. Optional. This object defines the cost charging properties 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 3-2.
If the request fails, the Status-Line header field will contain the status code and the reason for the failure. See "Errors and Exceptions".
The response body for the Make Call operation 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 3-2.
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@10.182.100.229:1", "charging": { "description":"testing", "amount":"11", "code":"1111", "currency":"rmb" }, "callingParty":"sip:bob@10.182.100.229:5020" }
Example 3-2 Make Call Response
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@10.182.100.229|-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@10.182.100.229|-50d94925ab34bf0"}
The Get Call Information operation retrieves the information on a previously-established call.
To retrieve the information on such a call, provide the appropriate call identifier in the GET request for this operation. This identifier should have been obtained by the initial set up request for the call.
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 machine 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 "Errors and Exceptions".
When the Get Call Information operation 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 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
These 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|CalledPartyBusy|CallingPartyNotReachable|CalledPartyNotReachable|CallHangUp|CallAborted" }}
Example 3-3 Get Call Information Request
The GET command to get information on the call contains the call identifier.
GET /rest/third_party_call/call/app-1q39oi07wpvjl|e9674e8214447c1663a016d434c@10.182.100.229|-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
Example 3-4 Get Call Information Response
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 Request 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, 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 the Cancel Call 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/cancel-call/${callIdentifier}
where:
host and port are the host name and port of the machine 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 "Errors and Exceptions".
Example 3-5 Cancel Call Request
The POST command to cancel the call contains the required call identifier.
POST /rest/third_party_call/cancel-call/app-1q39oi07wpvjl|e9674e8214447c1663a016d434c@10.182.100.229|-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 3-7 Error Response Example
If the Cancel Call Request operation 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@10.182.100.229|-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 machine 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 "Errors and Exceptions".
POST /rest/third_party_call/end-call/app-1q39oi07wpvjl|e9674e8214447c1663a016d434c@10.182.100.229|-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