RESTful Application Development Guide

     Previous  Next    Open TOC in new window    View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Interacting with the RESTful Facade

In order to interact with Oracle Communications Services Gatekeeper, applications use the RESTful Web Services Facade, or set of interfaces. The applications use standard HTTP requests in certain specialized ways. They add specific information to the header, and, in some cases, they send their message payload as an attachment. The following chapter provides an overview of how Oracle Communications Services Gatekeeper’s RESTful Web Services work, including:



Requests made using the RESTful facade have three basic parts:

In addition, MMS and WAP Push use HTTP Attachments.

Note: A generated HTML version of interface information is available from the root of each RESTful interface. For SMS, for example, the HTML is available at http://host:port/rest/sms/index.html where host and port are the values appropriate for an instance of Service Gatekeeper.


The most important part of a request made to the RESTful facade is the URI. It is made up of a sequence of sections, concantenated together. The general format of the URI is as follows:



The headers of all requests must include the HTTP Basic credentials “userid/password” as described in RFC 2617. The userid is the application’s application instance ID (for more information on the application instance ID, see Management Structures in the “Overview” chapter of this document.) Every request is authenticated by Oracle Communications Services Gatekeeper and must have these credentials.

Requests may also include other header data, including

In addition, the headers to the responses to certain requests may include a Location header value in the form of a key/value pair. This information designates the URI for the Bayeux server, used for retrieving notification or delivery status information concerning the initial request.

Service Correlation

In some cases the service that an application provides to its end-users may involve accessing multiple Oracle Communications Services Gatekeeper communication services. For example, a mobile user might send an SMS to an application asking for the pizza place 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 place, and then sends the user an MMS with all the appropriate information. Three Oracle Communications Services Gatekeeper communication services are involved in executing what for the application is a single service. In order to be able to correlate the three communication service requests, Oracle Communications Services Gatekeeper uses a Service Correlation ID, or SCID. This is a string that is captured in all the CDRs and EDRs generated by Oracle Communications 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.

The SCID is not provided by Oracle Communications Services Gatekeeper. 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.

Note: 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.

When the chain of services is initiated by a network-triggered request, Oracle Communications Services Gatekeeper calls an external interface to get the SCID. This interface must be implemented by an external system. No utility or integration is provided out of the box; this 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.

Parameter Tunneling

Parameter tunneling is a feature that allows an application to send additional parameters through Oracle Communications Services Gatekeeper so that a plug-in can use these parameters. This feature makes it possible for an application to tunnel parameters that are not defined in the application-facing interface but may be of use in Oracle Communications Services Gatekeeper’s interaction with the underlying network. It can be seen as an extension to the application-facing interface.


The body of the requests made to the RESTful facade may include additional data required for the request. This data is formatted using JSON. Depending on the request type, the body may be empty.


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. The content must have the following MIME header: Content-ID:messagePart Content-Type:application/json. In the RESTful interfaces delivered out of the box in Oracle Communications Services Gatekeeper multiple attachments are supported in both application-initiated and network-triggered messages.



The RESTful interfaces use standard HTTP methods in conjunction with the formats described in Format. In general, the RESTful facade uses these methods in the following way:


Retrieves the state of a resource.


Creates a new resource that does not yet have a URI; the request URI represents a parent or factory resource and multiple requests can create multiple new resources.


Creates a resource that has a pre-determined URI; this can be used to update a resource (or to start a stateful process).


Removes a resource.


Authentication and Security

The RESTful interfaces use HTTP basic authentication, using username/password. SSL is required. For more information on HTTP basic authentication, see RFC 2617 at


Notifications and Publish/Subscribe

In order to support the essentially asynchronous nature of notifications in an HTTP environment, the RESTful interfaces in Oracle Communications Services Gatekeeper rely on the publish/subscribe model supported by the Publish-Subscribe Server functionality of Oracle WebLogic Server 10.3. For more information on this model, please see “Using the HTTP Publish-Subscribe Server” in Developing Web Applications, Servlets, and JSPs For Oracle WebLogic Server at

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 as they become available. For more information on the Bayeux protocol, see the “Bayeux Protocol 1.0draft1” document at

The Bayeux client manages connecting to the server and subscribing to a channel. If the channel does not exist when the client subscribes to it, the channel is created. The channel name must begin with “/bayeux/${appInstanceId}”, where “appInstanceId” is the application’s application instance account ID. (For more information on application instances, see “Creating and Maintaining Service Provider and Application Accounts” in Managing Accounts and SLAs, another document in this set.) Applications can subscribe only to their own notifications: attempts to subscribe to notifications for other applications are rejected.

Note: The mechanisms for connecting to the server and subscribing to a channel are covered by the Bayeux protocol itself. Oracle Communications Services Gatekeeper delivers notifications to the channel; it is the client’s responsibility to interact with the Publish-Subscribe Server to access them. These mechanisms are outside the scope of the Oracle Communications Services Gatekeeper RESTful APIs.

Once the Bayeux client has connected to the server and subscribed to a channel, the RESTful client can start the notification. It does this by supplying the channel name as the endpoint in the start notification request.


Errors and Exceptions

If an operation is unsupported, a status code of 405 is returned. Policy Exceptions and Service Exceptions are mapped as described in Methods. In addition, Service Exception and Policy Exception objects are represented in the response body as JSON with the following form:

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

  Back to Top       Previous  Next