4 Using the RESTful Interfaces

General Format of a Request-URI

A fully qualified Request-URI consists of a sequence of concatenated sections that are each separated by a forward slash. For example:

https://host:port/rest_facade_context_root/URI/path_info_param/query-string

where,

• host:port: The hostname or IP address and port of your Services Gatekeeper installation; for example, 127.0.0.1 and 8001.

• rest_facade_context_root: The location of the set of resources that the particular interface uses; for example, rest, in the following example query for the status of a terminal:

  GET /rest/terminal_status/status?query="%7B%22address%22%3A%22tel%3A123%22%7D" HTTP/1.1
  

  In Services Gatekeeper, the rest_facade_context_root entry is always rest.

• URI: The location of a specific kind of functionality within the interface; for example, terminal_status.

• path_info_param: An identifier of a specific resource, for example, calls. This is seen in the Make Call request, POST /rest/third_party_call/calls HTTP/1.1. See Example 4-8. The path-info-param entry does not occur in all URIs.

• query_string: A set of name-value pairs that describes what is being requested; for example, status?query="%7B%22address%22%3A%22tel%3A123%22%7D, in the above GET query for rest_facade_context_root. The query-string entry is not seen in every URI.

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 example statement will set up a call between two parties:

POST /rest/third_party_call/calls HTTP/1.1

For the POST method:

• The URI in the request represents the factory resource accessed to create a resource. In Example 4-1, /rest/third_party_call/calls is the factory resource accessed to create a resource.

• The request body contains the information required to create the resource. See Example 4-6.

• If the resource is created, the response body will contain the identifier for the new resource. See Example 4-7. 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 start notifications on a specific terminal:

PUT /rest/terminal_location/periodic_notification HTTP/1.1

For the PUT method:

• The URI in the request represents the resource to update or the resource for which to start a stateful process. In Example 4-2, /rest/terminal_location/periodic_notification represents the resource accessed to start periodic notifications on a terminal's location.

• The request body will contain the required information. (The JSON object will contain, for example, information on the terminal, the criteria to monitor, the frequency and duration of the monitoring, where to place the notification, and the correlator to identify the session.

• The Location header in the response will specify the location that contains the resulting notifications. For example, the application may see the following header for the above PUT request:

  Location://terminalloc_host:port/rest/terminal/notifications
  

  In order to complete the operation, the application must access the specified location and use the correlator to retrieve the notifications.

• 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 as shown in Example 4-3, where an application attempts to retrieve the status of a terminal whose address is specified as "tel:123".

GET /rest/terminal_status/status?query=%7B%22address%22%3A%22tel%3A456%22%7D HTTP/1.1

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 Example 4-3, the value for status?query is ({"address":"tel:456"}, the unique address of the terminal in JSON representation).

• The request body will be empty.

• The response will provide information on the state of the resource.

  In order to complete the operation, the application must access the specified location and use the correlator to retrieve the notification.

• If the operation fails, the response body will contain the error response.

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-UR, as shown here:

DELETE /rest/terminal_status/notifications/6789 HTTP/1.1

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 Example 4-4, 6789 is the value which the application provided as the correlator when it requested notifications on a terminal's status.

• The request body will be empty.

• The response body will be empty.

• If the operation fails, the response body will contain the error response.

Headers for Multipart Messages with Attachments

The RESTful interfaces for Multimedia Messaging and WAP Push use HTTP attachments to transport their content. Both interfaces support multipart/form-data POST requests. When you use RESTful interfaces with Services Gatekeeper, 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 can 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 that has a value of form-data and a name attribute with the appropriate value. For example, the message part name is messagePart.

  • Content-Type header field that has a value of application/json and the charset attribute with the appropriate value.

  • Content-Transfer-Encoding field with the appropriate value.

• 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 actual message.

POST /rest/multimedia_messaging/messages HTTP/1.1
X-Session-ID: app: -123456789012346789
Authorization: Basic ZG9tY1uX3VzZXI6ZG9tYWluX3VzZXI=
X-Param-Keys:
X-Param-Values:
User-Agent: Jakarta Commons-HttpClient/3.0
Host: localhost:8001
Content-Length: 1215
Content-Type: multipart/form-data; boundary=kboiiFPAakDPYKeY7hBAW9I5c0rT48

--kboiiFPAakDPYKeY7hBAW9I5c0rT48
Content-Disposition: form-data; name="messagePart"
Content-Type: application/json; charset=US-ASCII
Content-Transfer-Encoding: 8bit

{
  "addresses":["tel:8765"],
  "subject":"Hello World",
  "priority":null,
  "senderAddress":"tel:1234",
  "charging":null
  "receiptRequest":
         {
           "correlator":"981234",
           "endpoint":"http://endpt_host:port/jaxws/MessageNotification",
           "interfaceName":"interfaceName",
         }
 }
--kboiiFPAakDPYKeY7hBAW9I5c0rT48
Content-Disposition: form-data; name="Attachment-txt-1"
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 8bit

This sentence represents the attachment text.
--kboiiFPAakDPYKeY7hBAW9I5c0rT48

Service Correlation

In some cases the service that an application provides to its end-users may involve accessing multiple Services Gatekeeper communication services.

For example, a mobile user might send an SMS to an application asking for a pizza restaurant 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 restaurant, and then sends the user an MMS with all the appropriate information. Three Services Gatekeeper communication services are involved in executing what, for the application, is a single service.

Services Gatekeeper uses a service correlation ID to correlate the three communication service requests. The service correlation ID (SCID) is a string that is captured in all the charging data records (CDRs) and event data records (EDRs) generated by 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.

Request Body

When present, the request body provides additional data required to complete the specific request. The following request body for an example Make Call operation provides the addresses of the called and calling parties and any charges to apply for the call:

{"calledParty":"sip:ann@sipcalled_host:port",
 "charging":null,
 "callingParty":"sip:zach@sipcalling_host:port"
}

Response Body

When present, the response body provides data that the application will need for later action. The following response body for the Make Call operation provides the application with the identifier for the call that was set up. The application will use this identifier to end the call, when necessary.

{"result":"app-1q39oi07wpvjl|e9674e8214447c1663a016d434c@sipcalling_host|-50d94925ab34bf0"}

Endpoint Addresses for RESTful Interfaces

The RESTful interfaces in Services Gatekeeper rely on the publish/subscribe model supported by the Publish-Subscribe Server functionality of Oracle WebLogic Server 10.3.1.

For more information on the publish/subscribe model, please see the discussion on "Using the HTTP Publish-Subscribe Server" in Oracle Fusion Middleware Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.

Understanding Bayeux Connections and Subscriptions

The mechanisms for connecting to the Web server and subscribing to a channel are covered by the Bayeux protocol itself. The Bayeux client manages connections to the server and subscriptions to a channel. If the channel does not exist when the client subscribes to it, the channel is created.

Once the Bayeux client connects to the server and subscribes to a channel, the RESTful client can start sending notifications. It does so by providing the Bayeux protocol channel name as the endpoint entry in a start notification request.

Understanding the Bayeux Protocol Channel Name

The Bayeux protocol channel name begins with /bayeux/appInstanceID where appInstanceID is the client application's application instance account ID. In Example 4-10, the appInstanceID is domain-user.

An application places the endpoint address for delivery notifications in the body of the request message. In the following example, it is inside a reference object.

...
 "reference":
        {"interfaceName":"interfaceName",
         "correlator":"6789",
         "endpoint":"/bayeux/domain-user/ts"
        }
...

See Example 12-5 for the complete request body of the status notification request.

For more information on application instances, see the discussion of application instances in Services Gatekeeper Portal Developer's Guide.

Using the Data at the Endpoint Address

Services Gatekeeper delivers notifications to the Bayeux channel name provided by the application in the associated request. It is the client's responsibility to interact with the publish/subscribe server to access the messages/data placed at the endpoint address. The mechanisms to do so are outside the scope of the Services Gatekeeper RESTful facades.