# RESTful Application Development Guide

# 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
- Methods
- Authentication and Security
- Notifications and Publish/Subscribe
- Errors and Exceptions

## Format

Requests made using the RESTful facade have three basic parts:

- URI
- Header
- Body

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.

### 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`

- URI

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.

Requests may also include other header data, including

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

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.

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

Retrieves the state of a resource.

- 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

Removes a resource.

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

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:

    {"error":

               {

               "type":"class name of the error object"

               "message":"error message, variable substitution will be performed for PX exceptions"

               }

      }