22 Using the OneAPI RESTful Interfaces

This chapter provides an overview of how the Oracle Communications Services Gatekeeper RESTful Web services work with OneAPI operations, and how you can use this functionality to interact with Services Gatekeeper.

About the OneAPI Facade Architecture

OneAPI operations are processed by the same network-facing interfaces that are used by the Services Gatekeeper RESTful facade for supported services.

For more information on communication services, see Services Gatekeeper Communication Service Reference Guide.

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.

See the discussion on OneAPI service facades in Services Gatekeeper Statement of Compliance for the specifications supported.

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

http://docs.oracle.com/middleware/1213/index.html

For information about JSR 311, see the GlassFish website:

http://jsr311.java.net

The supported OneAPI services include:

Multimedia messaging support
Payment support
Short Messaging support
Terminal location support

Support for Anonymous Customer References

Services Gatekeeper supports the use of Anonymous Customer References (ACRs) for all of the supported OneAPI services it supports. See "Adding RESTful Anonymous Customer Reference Support" for more information on the RESTFUL APIs.

Also see Services Gatekeeper Statement of Compliance for a link to the supported specification.

Components of the RESTful Facade

Figure 22-1 shows the multiple components of the Services Gatekeeper Access Tier (AT) RESTful facade.

Figure 22-1 RESTful Facade

Description of "Figure 22-1 RESTful Facade"

Network-facing (application-initiated) requests are received by the RESTful Servlet and 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 the network-triggered traffic and applications is handled by the same modules in reverse.

See Services Gatekeeper Communication Service Reference Guide for information on service enablers.

A Web Application Description Language (WADL) file generates the JAX-RS resource classes used by a communication service to translate between the RESTful request for delivery and 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 Services Gatekeeper Extension Developer's Guide.

Supported OneAPI Interfaces

Services Gatekeeper supports the following OneAPI Interfaces:

SMS
MMS
Terminal Location
Payment

There are a number of communication services for which OneAPI does not provide a standard interface. Services Gatekeeper supports these services using the proprietary RESTful interface. See "Creating Applications Using the RESTful Interfaces" for a complete list of supported services is available

The GSMA provides application developers OneAPI specifications for using these services when interacting with a OneAPI server. Services Gatekeeper, acting as a OneAPI server, provides response messages to operations as specified by the OneAPI specification.

SMS

Applications use the OneAPI RESTful Short Messaging interface (wlng_nt_sms_px21.ear) over SMPP to send and receive SMS messages, to fetch SMSs and delivery status reports, and to start and stop a notification.

When the request body for an SMS operation contains a request for a delivery receipt, the application provides a correlator for the message being sent and includes an endpoint address for returning the delivery notification.

See ”OneAPI Short Messaging/SMPP” in Services Gatekeeper Application Developer's Guide for a complete description of the OneAPI RESTful SMS interface.

MMS

Applications use the OneAPI RESTful Multimedia Messaging interface over MM7 (wlng_nt_multimedia_messaging_px21.ear) to send a multimedia message (MMS message) and to fetch information on MMS messages that have been received for the applications and stored by Services Gatekeeper.

Applications use the interface to fetch those messages, get delivery status on sent messages, and start and stop a notification.

See ”OneAPI Multimedia Messaging/MLP” in Services Gatekeeper Application Developer's Guide for a complete description of the OneAPI RESTful MMS interface, including example operations.

Terminal Location

Applications use the OneAPI RESTful Terminal Location interface over MLP (wlng_nt_terminal_location_px21.ear) to get a location for an individual terminal or a group of terminals.

See ”OneAPI Terminal Location/MLP” in Services Gatekeeper Application Developer's Guide for a complete description of the OneAPI RESTful Location interface, including example operations.

Payment

Applications use the OneAPI RESTful Payment interface over Diameter Ro (wlng_nt_sms_px21.ear) to charge an amount to an end-user's account, refund amounts to that account, query charge amount status and list charge amount transactions. Applications can also reserve amounts, reserve additional amounts, charge against the reservation and release the reservation.

See ”OneAPI Payment/Diameter” in Services Gatekeeper Application Developer's Guide for a complete description of the OneAPI RESTful Location interfaces.

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 interfaces facade, to the responses it receives from the interfaces 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 interfaces.

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 ”OneAPI Short Messaging/SMPP” in Services Gatekeeper Application Developer's Guide 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 number 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 subsequent OneAPI chapters about specific services.

POST

The POST method accesses a resource factory to create a 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 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 contains 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 contains the error response.

GET

The GET method retrieves the state of a specific resource that has been previously created. The specific resource is identified in the query string. For example, this statement can be used by an application to retrieve the location of a terminal whose address is "tel&3A%2B15415550100"::

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 is empty.
The response provides information on the location of the resource with an accuracy of 1000 meters. If the operation fails, it 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 to 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 is empty.
The response body is either empty, or contains 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==
```
See "Authentication and Security" for more information.
Accept: OneAPI only supports JSON as the response format. For example:
```
Accept: application/json
```
Location: Certain requests include location headers. They identify a new resource or redirect the recipient to a location other than the Request-URI to complete the request.
Content-Length: Specifies 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 22-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 22-1 lists some of the status codes and reason-phrases commonly encountered when interacting with the Services Gatekeeper OneAPI RESTful interfaces:

Table 22-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 website:

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

Message Body

Request or response message bodies are only present if required. A 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 22-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 needs for later action. Example 22-3 shows a response body for the Send SMS operation; it provides the application with the URI for the sent message.

Example 22-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 22-4 shows an application's request to query the location of a mobile terminal in the Service Gatekeeper OneAPI RESTful interface.

Example 22-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 22-5 shows the response which the application receives containing the terminal location information for the requested subscriber.

Example 22-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 website:

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 Services Gatekeeper OAuth Guide.

Notifications

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

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

Example 22-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 only subscribe to its own notifications (that is, to the notifications associated with its start notification requests). Any attempt to subscribe to notifications for other applications is 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"