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:

Format

URI

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:

https://host:port/{rest-facade-context-root)/{URI}/{path-info-param}/query-string

host:port

The hostname and port of the Oracle Communications Services Gatekeeper installation

rest-facade-context-root

The location of the set of resources that the particular interface uses. For out-of-the-box communication services, this is always rest

The location of a specific kind of functionality within the interface.

path-info-param

An identifier of a specific resource. Does not occur in all URIs

query-string

A set of name-value pairs that describes what is being requested. Does not occur in all URIs.

Header

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.

Session ID, if the Oracle Communications Services Gatekeeper installation is running in session mode. This is a key-value pair with key=X-Session-ID. For more information on sessions, see Session Manager.
Service correlation ID, 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, if the application wishes to supply parameters to be passed on to the network that are not supported in the RESTful interface itself. These are key-value pairs. For example:

X-Param-Keys=key1,key2
X-Param-Values=value1,value=2

For more information on tunneled parameters, sometimes called xparams, see Parameter Tunneling

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.

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.

Body

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.

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

Methods

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:

HTTP GET

The request is a query string and the resource is identified in that string. Complex object data structures are represented by JSON encoded strings in the URI. The body is empty. For example, to get the delivery status of an SMS, GET on http://host:port/rest/sms/delivery-status/requestID.
The response is an HTTP status code:

Success

200 with the body of the response containing a JSON representation of the resource

Error

500, for Service Exceptions of value SVC001
400, for all other Service and Policy Exceptions and other general errors such as Resource Not Found.

HTTP POST

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.

The URI of the request represents the factory resource. For example, to send an SMS, POST on http://host:port/rest/sms/messages. The body of the request contains a JSON representation of the resource to be created. The content type is application/json.
The response is an HTTP status code:

Success

201 with a JSON representation of the new resource in the body and a special Location header value that is equal to the URI of the new resource, if applicable.
204 with an empty body

Error

500, for Service Exceptions of value SVC001
400, for all other Service and Policy Exceptions and other general errors such as Resource Not Found.

HTTP PUT

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

The URI of the request is the pre-determined resource. For example, to start SMS notification, PUT on http://host:port/rest/sms/notification/. The body of the request contains a JSON representation of the resource to be created. The content type is application/json.
The response is an HTTP status code:

Success

201 and, if a new resource (for example, a notification) is created, a special Location header value that is equal to the URI of the new resource. The body contains a JSON representation of the new resource

Error

409 if a resource already exists and cannot be updated. For Service Exceptions of value SVC005 and SVC008.
500, for Service Exceptions of value SVC001
400, for all other Service and Policy Exceptions and other general errors such as Resource Not Found.

HTTP DELETE

The URI of the request is a string identifying the resource. For example, to stop an SMS notification, DELETE on http://host:port/rest/sms/notification/correlatorID. The body is empty.
The response is an HTTP status code:

Success

204 with an empty body

Error

404 for Service Exceptions of value SVC002
500, for Service Exceptions of value SVC001
400, for all other Service and Policy Exceptions and other general errors such as Resource Not Found.

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 http://www.ietf.org/rfc/rfc2617.txt

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 http://download.oracle.com/docs/cd/E12840_01/wls/docs103/webapp/.

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 http://svn.xantus.org/shortbus/trunk/bayeux/bayeux.html.

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.

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:

RESTful Application Development Guide