2 Interacting with the OneAPI RESTful Facade

This chapter provides an overview of how the Oracle Communications Services Gatekeeper RESTful Web Services work with the Oracle Communications Services Gatekeeper One API (OneAPI) SMS, MMS, Terminal Location, and Payment operations.

It describes the ways in which applications use OneAPI 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.

Services Gatekeeper supports OneAPI SMS, MMS, Payment, and Terminal Location operations as specified by the GSMA.

About RESTful Facade Architecture

Services Gatekeeper supports OneAPI operations by complying with industry specifications published by the GSMA and the Parlay Group. Services Gatekeeper uses an implementation of Oracle's JSR 311 Jersey Java API for RESTful Web Services (JAX-RS) to facilitate communication between applications and network nodes.

For information about Oracle JAX-RS, see the Oracle Fusion Middleware documentation:

http://download.oracle.com/docs/cd/E17904_01/web.1111/e13734/rest.htm

For information about JSR 311, see the GlassFish Web site:

http://jsr311.java.net/

OneAPI SMS, MMS, Terminal Location and Payment services are supported.

RESTful Facade Modules

The Services Gatekeeper Access Tier (AT) RESTful facade consists of multiple modules as shown in the following figure.

Figure 2-1 RESTful Facade

Description of "Figure 2-1 RESTful Facade"

Southbound (application-initiated) requests are received by the RESTful Servlet and are then directed to the RESTful handler chain in preparation for delivery by the JAX-RS. The JAX-RS communicates the RESTful requests to the appropriate Service Enabler for execution at the network tier by the correct Service Enabler Enterprise JavaBean (EJB). Communication between northbound (network-triggered) traffic and applications is handled by the same modules in reverse.

For information on Service Enablers, see Oracle Communications Services Gatekeeper Communication Service Guide.

A Web Application Description Language (WADL) file is used to generate the JAX-RS resource classes used by a communication service to translate between the RESTful request for delivery to the appropriate EJB. For information on WADL, see:

http://wadl.java.net/

For information on creating communication services from WADL files, see the discussion on Using Services Gatekeeper with REST Services in the release notes.

About Configuring OneAPI Server Functionality

The Services Gatekeeper OneAPI server functionality is embedded in the Parlay X plug-in, which is installed and deployed by default. No additional OneAPI configuration is necessary.

General Format of an Operation

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

Request-URI and HTTP Methods in requests and Status -Line in responses
Headers
Message Body
Attachments

Request-URI and HTTP Methods

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

Here is an example of the OneAPI POST method used to send an SMS message. The request URI is contained in the first line of the example.

POST http://example.com/oneapi/1/smsmessaging/outbound/tel%3A%2B5550100/requests
HTTP/1.1
Host: example.com:80
Content-Type: application/x-www-form-urlencoded
Accept: application/json
 address=tel%3A%2B15415550100&
address=tel%3A %2B15415550101&
senderAddress=tel:%2B5550100&
message=Hello%20World&
clientCorrelator=123456&
notifyURL=http://application.example.com/notifications/DeliveryInfoNotification&
callbackData=some-data-useful-to-the-requester&
senderName=ACME%20Inc.

See Chapter 3, "OneAPI Short Messaging," for information on the parameters used in this example request.

General Format of a Request-URI

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

http://host:port/oneapi/api_version/service/service_specific_sections

where,

host:port: The hostname and port of your Services Gatekeeper OneAPI installation; for example, 127.0.0.1 and 8001.
api_version: The version of the OneAPI interface deployed.

In Services Gatekeeper, the current api version is always 1.
service: The communication service required by the method. For example, smsmessaging.
service_specific_sections: One or more sections required by the OneAPI specification for the method called. See the examples provided in the following service-specific chapters for more information on required sections.

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 sets up a subscription to SMS delivery notifications:

POST http://example.com/oneapi/1/smsmessaging/outbound/tel%3A%2B5550100/subscriptions HTTP/1.1

For the POST method:

The URI in the request represents the factory resource that is accessed to create a new resource. In the above example, /smsmessaging/outbound/tel%3A%2B5550100/subscriptions is the factory resource accessed to create a resource.
The request body contains the information required to create the resource.
If the resource is created, the response body will contain the identifier for the new resource. If the operation fails, the response body will contain the error response.

PUT

The PUT method creates a resource that has a predetermined 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 release a payment reservation:

PUT http://example.com/oneapi/1/payment/tel%3A%2B5550100/transactions/amountReservation/abc123

For the PUT method:

The URI in the request represents the resource to update or to start a stateful process on. In the example, /tel%3A%2B5550100/transactions/amountReservation/abc123 represents the resource accessed to release the payment reservation.
The request body for this operation will contain the required information. The JSON object will contain, for example, information on the description and amount of the reservation to release.
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. For example, an application attempts to retrieve the location of a terminal whose address is "tel&3A%2B15415550100" by using the following statement:

GET http://example.com/oneapi/1/location/queries/location?&address=tel&3A%2B15415550100&requestedAccuracy=1000

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 (location?&address) is the unique address of the terminal. (It is the address of the terminal, {"address":"tel:15415550100",} in JSON representation).
The request body for this operation will be empty.
The response will provide information on the location of the resource with an accuracy of 1000 meters. 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. An application stops SMS delivery notifications with the following request:

DELETE http://example.com/oneapi/1/smsmessaging/outbound/subscriptions/abc123

For the DELETE method:

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

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".
Accept: OneAPI only supports JSON as the response format. For example:
```
Accept: application/json
```
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.
Content-Length: This is 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, application/json, application/x-www-form-urlencoded or application/xml.

The multipart/form-data value for the Content-Type header field is described in the next section.
X-Session-ID: A session ID is required if transaction sessions are used.

Headers for Multipart Messages with Attachments

The OneAPI RESTful-based communication services for Multimedia Messaging use HTTP attachments to transport their content. The OneAPI MMS interface supports 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 contains a name attribute with the appropriate value. For example, the Message Part name is messagePart. For Multimedia Messages the attribute is attachments. Multimedia messages contain an additional filename attribute and value.
- Content-Type header field whose value describes the data format included in the message part.
- Content-Transfer-Encoding field with the appropriate value, if needed.
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 message.

Example 2-1 Example of a Multipart Message Request

POST http://example.com/oneapi/1/messaging/outbound/ tel%3A%2B5550100/requests HTTP/1.1
Content-Length: 12345
Content-Type: multipart/form-data;
boundary="===============123456==";
    
MIME-Version: 1.0
Host: www.example.com
Date: Thu, 04 Jun 2009 02:51:59 GMT
 
--===============123456==
Content-Disposition: form-data; name=”root-fields”
Content-Type: application/x-www-form-urlencoded;
address=tel%3A%2B15415550100&
address=tel%3A%2B15415550101&
senderAddress=tel:%2B5550100&
&senderName=ExampleSender
Subject=My%20message&
notifyURL=http://example-application.com/notifications/DeliveryInfoNotification/54311
&callbackData=
&clientCorrelator=123456
--===============123456==
Content-Disposition: form-data; name=”attachments”; filename=”picture.jpg”
Content-Type: image/gif
 
GIF89a...binary image data...
--===============123456==-

Status-Line

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

HTTP/1.1 status_code reason_phrase

where:

status_code is a three-digit number that indicates the success or failure to fulfill the request.
reason_phrase is 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 the Services Gatekeeper OneAPI 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
400	Bad Request	The request cannot be processed. Check the error message for details.
401	Authentication failure	The authentication to the protected resource failed. Check your Services Gatekeeper OneAPI authentication requirements.
403	Forbidden	The authentication credentials provided in the request are not valid.
404	Not found	The resource specified in the URI cannot be found.
405	Method not supported	The method requested is not supported by the service.
501	Internal Server Error	Failure: An unexpected condition prevented the server from fulfilling the request.
503	Server busy and service unavailable. Please retry the request.	The server hosting Services Gatekeeper OneAPI RESTful interface is busy.

The Status-Codes used by OneAPI and supported by Services Gatekeeper conform to Internet Engineering Task Force (IETF) standards. For a complete listing of the HTTP Status Codes and their definitions, see RFC 2616 on the IETF Web site:

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

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 Send SMS operation provides the addresses of the recipients and sending party, and the message text:

Example 2-2 Send SMS Request

address=tel%3A%2B15415550100&
address=tel%3A %2B15415550101&
senderAddress=tel:%2B5550100&
message=Hello%20World&

Response Body

When present, the response body provides data that the application will need for later action. The following response body for the Send SMS operation provides the application with the URI for the sent message.

Example 2-3 Response Body for Send SMS Request

{"resourceReference": {"resourceURL": " http://example.com/1/smsmessaging/outbound/ tel%3A%2B5415550100/requests/abc123"}}

Example of a Request and Response

Example 2-4 shows an application's request to query the location of a mobile terminal in the Service Gatekeeper OneAPI RESTful interface.

Example 2-4 Request Associated with Get Terminal Location

GET http://example.com/oneapi/1/location/queries/location?&address=tel&3A%2B15415550100&requestedAccuracy=1000 HTTP/1.1
Host: example.com:80
Accept: application/json

Example 2-5 shows the response which the application receives containing the terminal location information for the requested subscriber.

Example 2-5 Response Associated with a Get Terminal Location Operation

HTTP/1.1 200 OKContent-Type: application/json
Content-Type: application/json
Content-Length: 1234
Date: Thu, 04 Jun 2009 02:51:59 GMT
 
{"terminalLocationList": {"terminalLocation": {
    "address": "tel:15415550100",
    "currentLocation": {
        "accuracy": "100",
        "altitude": "1001.0",
        "latitude": "-80.86302",
        "longitude": "41.277306",
        "timestamp": "2009-06-03T00:27:23.000Z"
    },
    "locationRetrievalStatus": "Retrieved"
}}}

Authentication and Security

The OneAPI RESTful interfaces in Services Gatekeeper use HTTP basic authentication, using username and password. SSL is required. For example:

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

For more information on HTTP basic authentication, see RFC 2617 on the IETF Web site:

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

Services Gatekeeper supports sessionID security with use of the X-SessionID header.

Services Gatekeeper also supports subscriber authentication and authorization for access to protected resources by supporting OAuth 2.0. For information on using OAuth 2.0, see the chapter on Services Gatekeeper OAuth 2.0 Authorization Server in the release notes.

Notifications

When an application needs to receive a notification, about a message delivery receipt for example, the application posts a subscription request containing a notificationURL location where Services Gatekeeper delivers the notification.

Example 2-6 shows a POST operation subscribing to SMS delivery notifications for a senderAddress. The notificationURL is included in the message body.

Example 2-6 SMS Delivery Notification Subscription POST Request

POST http://example.com/oneapi/1/smsmessaging/outbound/ tel%3A%2B5550100/subscriptions HTTP/1.1
Host: example.com:80
Content-Type: application/x-www-form-urlencoded
Accept: application/json
 
notifyURL=http://www.yourURL.here&
criteria="SampleCriteria"&
callbackData=doSomething()

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.

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 objects of the following form:

{"requestError":
           {
           "policyException":"class name of the error object"
                      {
              "messageID": "System Generated ID:
              "text":"error message"
              "variables"""relevant string"
              }
           }
 }

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"