2 Interacting with the RESTful Facade

This chapter provides an overview of how Oracle Communications Services Gatekeeper's RESTful Web Services work.

It describes the ways in which applications use standard HTTP methods in association with the RESTful Web Services facade to interact with Services Gatekeeper. Applications add specific information to the request headers, and, in some cases, they send their message payload as an attachment.

General Format of an Operation

The following basic elements are present in the requests that an application makes to the RESTful facade and/or the responses it receives from the facade:

Request-URI and HTTP Methods in requests and Status-Line in responses
Headers
Message Body
Attachments: Sometimes messages (for example, multimedia messaging) contain attachments. Special headers are provided to specify the details when a message has multiple parts. See "Headers for Multipart Messages with Attachments".

Request-URI and HTTP Methods

Applications use one of four methods, "GET", "POST", "PUT", or "DELETE", to request a required action to be performed on an abstract or physical resource, a specific Uniform Resource Identifier (URI). The Request-URI, the abstract or physical resource which an HTTP method acts upon or uses is therefore the most important part of any request that an application makes to the RESTful facade.

Here is the GET method used to query for the status of a terminal:

GET /rest/terminal_status/status?query="%7B%22address%22%3A%22tel%3A123%22%7D" HTTP/1.1

where, the string %7B%22address%22%3A%22telA123%22%7D is the address of the terminal (or the {"address":"tel:123"} JavaScript Object Notation (JSON) object).

General Format of a Request-URI

A fully qualified Request-URI is made up of a sequence of sections, concatenated as:

https://host:port/rest_facade_context_root/URI/path_info_param/query-string

where,

host:port: The hostname and port of your Services Gatekeeper installation; for example, 127.0.0.1 and 8001.
rest_facade_context_root: The location of the set of resources that the particular interface uses; for example, rest, in the above section.

In Services Gatekeeper, the rest_facade_context_root entry is always rest.
URI: The location of a specific kind of functionality within the interface; for example terminal_status, as in the above section.
path_info_param: An identifier of a specific resource, for example, calls. This is seen in the Make Call request, POST /rest/third_party_call/calls HTTP/1.1. See Example 2-4. The path-info-param entry does not occur in all URIs.
query_string: A set of name-value pairs that describes what is being requested; for example, status?query="%7B%22address%22%3A%22tel%3A123%22%7D, in the above section. The query-string entry is not seen in every URI.

POST

The POST method accesses a resource factory to create a new resource that does not yet have a URI. Multiple requests to a resource factory can create multiple new resources.

The following statement will set up a call between two parties:

POST /rest/third_party_call/calls HTTP/1.1

For the POST method:

The URI in the request represents the factory resource accessed to create a new resource. In the above example, (/rest/third_party_call/calls) is the factory resource accessed to create a resource.
The request body contains the information required to create the resource. See Example 2-4.
If the resource is created, the response body will contain the identifier for the new resource. See Example 2-5. If the operation fails, the response body will contain the error response.

PUT

The PUT method creates a resource that has a pre-determined URI. This method can be used to update a resource (or to start a stateful process). For example, an application uses the following statement to start notifications on a specific terminal:

PUT /rest/terminal_location/periodic_notification HTTP/1.1

For the PUT method:

The URI in the request represents the resource to update or to start a stateful process. In the example, (/rest/terminal_location/periodic_notification) represents the resource accessed to start periodic notifications on a terminal's location.
The request body for this operation will contain the required information. (The JSON object will contain for example, information on the terminal, the criteria to monitor, the frequency and duration for the monitoring, where to place the notification, and the correlator to identify the session.
The Location header in the response will specify the location that contains the resulting notifications. For example, the application may see the following header for the above PUT request:
```
Location://10.182.100.245:9001/rest/terminal/notifications
```
In order to complete the operation, the application must access the specified location and use the correlator to retrieve the notifications.
If the operation fails, the response body will contain the error response.

GET

The GET method retrieves the state of a specific resource that has been previously set up. The specific resource is identified in the query string, as shown above. An application attempts to retrieve the status of a terminal whose address is "tel:123" with the following:

GET /rest/terminal_status/status?query=%7B%22address%22%3A%22tel%3A456%22%7D HTTP/1.1

For the GET method:

The URI in the request represents the query string that uniquely identifies the resource whose status the application wishes to retrieve. In the example, the value for (status?query=) is the unique address of the terminal. (It is the address of the terminal, {"address":"tel:456"} in JSON representation).
The request body for this operation will be empty.
The response will provide information on the state of the resource. If the operation fails, it will contain the error response

In order to complete the operation, the application must access the specified location and use the correlator to retrieve the notification.

DELETE

The DELETE method removes a specified resource. The application provides the correlator or the identifier for the resource that must be removed in the Request-URI. For example:

DELETE /rest/terminal_status/notifications/6789 HTTP/1.1

For the DELETE method:

The URI in the request contains the correlator, a value that uniquely identifies the resource the application wishes to remove. In the example, 6789 is the value which the application provided as the correlator when it requested for notifications on a terminal's status.
The request body for this operation will be empty.
The response body will be empty. If the operation fails, it will contain the error response.

Status-Line

The Status-Line is the first line in any response that an application receives when it interacts with the RESTful services interface in Services Gatekeeper. It takes the form:

HTTP/1.1 Status-Code Reason-Phrase

where,

Status-Code: A three-digit indicator of the success or failure to fulfill the request.
Reason-Phrase: A brief description of the (successful) action performed; or the reason for the failure.

For example:

HTTP/1.1 201 Created

Table 2-1 lists some of the status codes and reason-phrases commonly encountered when interacting with Services Gatekeeper's RESTful interfaces:

Table 2-1 A Sampling of Status Codes and Reason Phrases

Status-Code	Reason-Phrase	Description
200	OK	Success.
201	Created	Success. The requested resource was created.
204	No Content	Success
501	Internal Server Error	Indicates failure. An unexpected condition prevented the server from fulfilling the request.

For a complete listing of the HTTP Status Codes and their definitions, see RFC 2616 at

http://www.ietf.org/rfc/rfc2616.txt

Headers

The requests and responses for RESTful operations include the following header fields:

Authorization: The Authorization header field is a required field and is found in all requests. It indicates the type of authentication and security. For example:
```
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
```
For more information, see "Authentication and Security".
Session ID: When Services Gatekeeper is running in Session mode, the X-Session-ID header must be present in all request messages to identify the application.

In session mode, an application's first task is to obtain a session ID from the Session Manager. All traffic requests (for that session) include this identifier in the key-value pair for the X-Session-ID key. For example:
```
X-Session-ID: app: -1780934689905632396
```
The X-Session-ID header is not present when Services Gatekeeper is running in Sessionless mode. For more information on sessions, see Chapter 14, "Session Manager."
Service correlation ID (X-SCID): The X-SCID header will be present if the application wishes to set up service correlation. This is a key-value pair with key=X-SCID. For more information on service correlation, see "Service Correlation".
Tunneled parameters: Tunneled parameters (also called xparams) are present if the application wishes to supply parameters that are not supported in the RESTful interface itself and need to be passed on to the network. The key-value pairs are:
- X-Param-Key and X-Param-Values: The X-Param-Key and X-Param-Values headers are found in the requests.
- X-Plugin-Param-Key and X-Plugin-Param-Values: The X-Plugin-Param-Key and X-Plugin-Param-Values headers are returned in the response headers.
See the appropriate sections in the Communication Service Guide for descriptions of the tunneled parameters that are applicable to your communication service.
Location: Location headers are found in responses to certain requests. They are used for the identification of a new resource or to redirect the recipient to a location other than the Request-URI for completion of the request.

The Location header in Example 2-5 contains the call identifier for a newly-setup call. In Example 8-12, it specifies the location that the application must access to receive notifications about a terminal (for which the application had previously initiated a notification request).
Content-Length: The length of the request (or response) body.
Content-Type: The MIME-type value for the Content-Type header field may be multipart/form-data or application/json. The multipart/form-data value for the Content-Type header field is described in the next section.

Headers for Multipart Messages with Attachments

The RESTful-based communication services for Multimedia Messaging and WAP Push use HTTP attachments to transport their content. Both interfaces support multipart/form-data POST requests. When you use RESTful interfaces with the base Services Gatekeeper product, multiple attachments are supported in both application-initiated and network-triggered messages.

When a request message contains one or more messages embedded within it, a specified boundary is placed between the parts of the message and at the beginning and end of the message. For multipart message requests:

The MIME-type value for the Content-Type header field may be multipart/form-data or application/json. If the MIME-type value for the Content-Type header field is multipart/form-data, the boundary= entry is used to provide a value for the boundary between the message parts.
Each message part contains the following:
- Content-Disposition header field whose value is form-data and a name attribute with the appropriate value. For example, the Message Part name is messagePart.
- Content-Type header field whose value is application/json and the charset attribute with the appropriate value.
- Content-Transfer-Encoding field with the appropriate value.
If the content of the message is pure ASCII, the response body contains the message. Otherwise the response body contains an identifier that is used to fetch the actual message.

Example 2-1 Example of a Multipart Message Request

POST /rest/multimedia_messaging/messages 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: 1215
Content-Type: multipart/form-data; boundary=kboiiFPAakDPYKeY7hBAW9I5c0rT48

--kboiiFPAakDPYKeY7hBAW9I5c0rT48
Content-Disposition: form-data; name="messagePart"
Content-Type: application/json; charset=US-ASCII
Content-Transfer-Encoding: 8bit

{
  "addresses":["tel:8765"],
  "subject":"Hello World",
  "priority":null,
  "senderAddress":"tel:1234",
  "charging":null
  "receiptRequest":
         {
           "correlator":"981234",
           "endpoint":"http://10.182.100.229:13444/jaxws/MessageNotification",
           "interfaceName":"interfaceName",
         }
 }
--kboiiFPAakDPYKeY7hBAW9I5c0rT48
Content-Disposition: form-data; name="Attachment-txt-1"
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit

This is the attachment text.
--kboiiFPAakDPYKeY7hBAW9I5c0rT48

Service Correlation

In some cases the service that an application provides to its end-users may involve accessing multiple Services Gatekeeper communication services.

For example, a mobile user might send an SMS to an application asking for a pizza restaurant nearest to his current location. The application then makes a Terminal Location request to find the user's current location, looks up the address of the closest pizza restaurant, and then sends the user an MMS with all the appropriate information. Three Services Gatekeeper communication services are involved in executing what for the application is a single service.

Services Gatekeeper uses a Service Correlation ID to correlate the three communication service requests. The Service Correlation ID (SCID) is a string that is captured in all the Charging Data Records (CDRs) and Event Data Records (EDRs) generated by Services Gatekeeper. The CDRs and EDRs can then be orchestrated in order to provide special treatment for a given chain of service invocations, by, for example, applying charging to the chain as a whole rather than to the individual invocations.

How Service Correlation IDs are Provided

Services Gatekeeper does not provide the Service Correlation ID. The type of request determines the Service Correlation ID:

Application-Initiated Requests: When the chain of services is initiated by an application-initiated request, the application must provide and ensure the uniqueness of the SCID within the chain of service invocations.

In certain circumstances, it is also possible for a custom service correlation service to supply the SCID, in which case it is the custom service's responsibility to ensure the uniqueness of the SCID.
Network-Triggered Requests: When the chain of services is initiated by a network-triggered request, Services Gatekeeper calls an external interface to get the SCID.

Note that, this interface must be implemented by an external system. Integration of such an external interface must be a part of a system integration project. It is the responsibility of the external system to provide, and ensure the uniqueness of, the SCID.

Message Body

The message body for a request or response is present only when required. The message body is a JSON object.

Request Body

When present, the request body provides additional data required to complete the specific request. The following request body for an example Make Call operation provides the addresses of the called and calling party and any charges to apply for the call:

Example 2-2 Request Body for Make Call

{"calledParty":"sip:ann@10.182.100.229:1",
 "charging":null,
 "callingParty":"sip:zach@10.182.100.229:5020"
}

Response Body

When present, the response body provides data that the application will need for later action. The following response body for the Make Call operation provides the application with the identifier for the call that was set up. The application will use this identifier to end the call, when necessary.

Example 2-3 Response Body for Make a Make Call Operation

{"result":"app-1q39oi07wpvjl|e9674e8214447c1663a016d434c@10.182.100.229|-50d94925ab34bf0"}

Example of a Request and Response

Example 2-4 shows an application's request to set up a call between two parties using the Make Call operation in Service Gatekeeper's RESTful interface.

Example 2-4 Request associated with a Make Call Operation

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":"init_call",
       "amount":"11",
       "code":"1111",
       "currency":"rmb"
      },
 "callingParty":"sip:bob@10.182.100.229:5020"
}

Example 2-5 shows the response which the application receives for a successful setup of the requested call.

Example 2-5 Response associated with a Make Call Operation

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

Authentication and Security

The RESTful interfaces use HTTP basic authentication, using username/password. SSL is required. For instance:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

For more information on HTTP basic authentication, see RFC 2617 at http://www.ietf.org/rfc/rfc2617.txt

Notifications and Publish/Subscribe

When an application needs to receive a notification, (about a message delivery receipt for example), the application uses the publish/subscribe functionality in Services Gatekeeper.

An application can subscribe only to its own notifications (that is, to the notifications associated with its start notification requests). Any attempt to subscribe to notifications for other applications will be rejected.

Supported Endpoint Addresses

The application provides an endpoint address that resides on a publish/subscribe server. It is possible to specify one of the following endpoint addresses:

RESTful: a Bayeux protocol channel name
SOAP: a Web service implemented by the application

A SOAP endpoint for the notification of a message sent using RESTful interfaces in Services Gatekeeper is valid only if the SOAP and RESTful interfaces reside in the same cluster.

Endpoint Addresses for RESTful Interfaces

The RESTful interfaces in Services Gatekeeper rely on the publish/subscribe model supported by the Publish-Subscribe Server functionality of Oracle WebLogic Server 10.3.1.

For more information on the publish/subscribe model, please see “Using the HTTP Publish-Subscribe Server” in Oracle Fusion Middleware Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server at: http://download.oracle.com/docs/cd/E15523_01/web.1111/e13712/pubsub.htm.

Bayeux Protocol

When using RESTful interfaces, the application client must use the Bayeux protocol to communicate with the server. In this model, clients subscribe to a channel (similar to a topic in JMS) and receive messages (notifications) as they become available. The endpoint address resides on a Bayeux server.

Connections and Subscriptions

The mechanisms for connecting to the server and subscribing to a channel are covered by the Bayeux protocol itself. The Bayeux client manages connections to the server and subscriptions to a channel. If the channel does not exist when the client subscribes to it, the channel is created.

Once the Bayeux client connects to the server and subscribes to a channel, the RESTful client can start sending notifications. It does so by providing the Bayeux protocol channel name as the endpoint in a start notification request.

Bayeux Protocol Channel Name

The Bayeux protocol channel name begins with /bayeux/appInstanceID where appInstanceID is the client application's application instance account ID. In Example 2-6, the appInstanceID is domain-user.

An application places the endpoint address for such delivery notifications in the body of the request message. Below, it is inside a reference object.

Example 2-6 Example of an Endpoint Address in a Reference Object

...
 "reference":
        {"interfaceName":"interfaceName",
         "correlator":"6789",
         "endpoint":"/bayeux/domain-user/ts"
        }
...

See Example 7-5 for the complete request body.

For more information on application instances, see “Creating and Maintaining Service Provider and Application Accounts” in Accounts and SLAs Guide.)

Using the Data at the Endpoint Address

Services Gatekeeper delivers notifications to the Bayeux channel name provided by the application in the associated request. It is the client's responsibility to interact with the Publish-Subscribe Server to access the messages/data placed at the endpoint address. The mechanisms to do so are outside the scope of the Services Gatekeeper RESTful Web Services.

For more information about the Bayeux protocol, see the Bayeux specification document at

http://svn.xantus.org/shortbus/trunk/bayeux/bayeux.html

Errors and Exceptions

The Status-Line in the response message indicates the protocol version, the three-digit Status Code and the reason for the failure of the request.

In addition, Service Exception and Policy Exception objects are represented in the response body as JSON with the following form:

{"error":
           {
           "type":"class name of the error object"
           "message":"error message, variable substitution will be performed for PX exceptions"
           }
  }

For Service Exceptions, the value for type is:

"type":"org.csapi.schema.parlayx.common.v2_1.ServiceException"

For Policy Exceptions, the value for type is:

"type":"org.csapi.schema.parlayx.common.v2_1.PolicyException"