Skip Headers
Oracle® Communications Services Gatekeeper RESTful Application Developer's Guide
Release 5.1
E37533-01
Go to Documentation Home
Home		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us
Go to previous page
Previous		 Go to next page
Next
PDF · Mobi · ePub

3 Third Party Call

This chapter describes the operations in the Third Party Call interface of the RESTful Web Services provided in Oracle Communications Services Gatekeeper.

About RESTful Third Party Call Interface

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.

REST Service Descriptions Available at Run-time

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.

Make Call

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.

Authorization

Basic

HTTP Method

POST

URI

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.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

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"
  }
}

Response Header

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".

Response Body

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.

Examples

Example 3-1 Make Call Request

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"}

Get Call Information

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.

Authorization

Basic

HTTP Method

GET

URI

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.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

There is no request body.

Response Header

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".

Response Body

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"
}}

Examples

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"
  }
}

Cancel Call Request

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.

Authorization

Basic

HTTP Method

POST

URI

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.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

There is no request body.

Response Header

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".

Response Body

There is no response body.

Examples

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-6 Cancel Call Response

If the Cancel Call Request operation 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 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"
   }
}

End Call

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.

Authorization

Basic

HTTP Method

POST

URI

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.

Request Header

The MIME-type for the Content-Type header field is application/json.

Request Body

There is no request body.

Response Header

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".

Response Body

There is no response body.

Examples

Example 3-8 End Call Request

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

Example 3-9 End Call Response

If the End Call operation 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
Go to previous page
Previous		 Go to next page
Next
Go to Documentation Home
Home		 Go to Table of Contents
Contents		 Go to Feedback page
Contact Us