26 Managing REST Services

26.1 What You Should Know About REST Services

REST (REpresentational State Transfer) is an architectural style for making distributed resources available through a uniform interface that includes uniform resource identifiers (URIs), well-defined operations, hypermedia links, and a constrained set of media types. Typically, these operations include reading, writing, editing, and removing. Media types include JSON and XML/ATOM.

REST APIs are commonly used in client-side scripted, Rich Internet Applications. For example, a browser-based application written in Javascript can use Ajax techniques with REST APIs to send and receive application data from the server and update the client view.

WebCenter provides a RESTful interface to many of its services, like Discussions, Lists, People Connections, and Search. For a complete list of the services that support REST, see "Using Oracle WebCenter REST APIs" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.

For a more complete introduction to REST and the WebCenter REST APIs, see "Using Oracle WebCenter REST APIs" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.

26.2 Performing Required Manual Configurations to Enable REST

The WebCenter REST services are not enabled by default. To enable the REST services to work, you must perform a manual configuration procedure. This procedure prepares the credential store to handle encrypted security tokens.

For detailed information on the required configuration steps see "Before Using REST: Perform This Required Manual Configuration" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.

26.3 Understanding Security Tokens

A user-scoped security token is embedded in the href and template attributes of every REST service URI. The token is both generated and validated by the server. The purpose of the security token is to prevent Cross-Site Request Forgery (CSRF) attacks.

For example:

<link
  template="opaque-template-uri/@me?startIndex={startIndex}
    &itemsPerPage={itemsPerPage}&token=generated-token"
  resourceType="urn:oracle:webcenter:messageBoard"
  href="opaque-uri/@me?token=generated-token"
  capabilities="urn:oracle:webcenter:read"/>

Security tokens are based on the authenticated user's name. They do not expire, making it possible to both cache and bookmark the URIs.

Security tokens are also "salted," a cryptographic technique of adding extra characters to a string before encrypting it. Because of salting, if a security token is compromised, you will not have to change the user's user name across the entire system to address the problem.

This technique prevents cases where a user name is compromised and you don't want to have to change the user name system wide to fix the problem.

For more information on security tokens, see "Security Considerations for WebCenter REST APIs" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.

26.4 Configuring a Proxy Server

This section explains how to set up a simple, response-rewriting reverse HTTP proxy on an Apache server. A proxy server is typically employed to avoid cross-domain request problems associated with making XMLHttpRequest (XHR) calls from a browser client. These calls are typically associated with the Ajax development technique for creating rich, interactive client-side interfaces. REST APIs are typically used within this kind of client-side development scenario.

The basic steps for setting up a proxy server on Apache are:

1. Obtain access to an Apache server. Oracle recommends Apache 2.2.7 or a later version.

2. Make sure the server has the mod_substitute module installed. Note that Apache versions 2.2.7 and later include mod_substitute by default. It is also possible to use mod_sed or mod_line_edit, however these configurations are not supported by Oracle.

3. Open the httpd.conf or the virtual host config file, and add the following lines, substituting your server name/information where appropriate:

   ProxyRequests           Off
   LoadModule              substitute_module       modules/mod_substitute.so
   SetOutputFilter         SUBSTITUTE
    
   ProxyPass               /rest/api/              http://myhost:8888/rest/api/
   ProxyPassReverse        /rest/api/              http://myhost:8888/rest/api/
   Substitute              s|myhost|yourhost|n
    
   ProxyPass               /rpolk/rest/api/        http://myhost:8888/rest/api/
   ProxyPassReverse        /rpolk/rest/api/        http://myhost:8888/rest/api/
   Substitute              s|myhost:8888/rest/api|yourhost/rpolk/rest/api|n
   

   Note:

   Two servers are being proxied in this example scenario. Note that the following two calls are actually talking to these two different servers, but they appear to clients to be the same server host:

   http://myhost/rest/api/resourceIndex

   http://myhost/rpolk/rest/api/resourceIndex

4. Restart the Apache server. For example, on Linux, you could do this:

   sudo /etc/init.d/httpd restart
   

Note that on some configurations of Linux, proxying with Apache in this fashion requires you tell selinux to allow outbound connections from httpd. You can accomplish this by enabling the httpd_can_network_connect flag in selinux's GUI or through the command line.

26.5 Changing the REST Root Name

Although not required, in some cases you might want to change the root name for the REST APIs. The recommended technique for changing the REST root name is to do so by configuring a proxy server. For example, through the proxy server configuration described in Section 26.4, "Configuring a Proxy Server," the following two URIs refer to the same server:

http://10.143.122.163/rest/api/resourceIndex

http://10.143.122.163/rpolk/rest/api/resourceIndex

26.6 Using Compression

This section explains techniques for enabling compression on the XML or JSON responses that are returned to the client by the REST APIs.

If you are running Apache, you can add the mod_deflate or mod_gzip server modules to the server configuration. Refer to the Apache documentation for more information.

If you are using Oracle HTTP Server (OHS), Oracle recommends using Oracle Web Cache for this purpose. For detailed information, see Oracle Fusion Middleware Administrator's Guide for Oracle Web Cache.

If you are using OHS, you can also add the mod_deflate or mod_gzip server module to enable compression. For detailed information on this technique, see "Understanding Oracle HTTP Server Modules" in the Oracle Fusion Middeware Administrators Guide for Oracle HTTP Server.

For more information on Oracle Web Cache, see the section "Compression" in the Oracle Fusion Middeware Administrators Guide for Oracle HTTP Server, and see the chapter "Caching and Compressing Content" in the same guide.

26.7 Handling Authentication

By default, REST services are configured to accept authentication from identity assertion providers. If no identity assertion providers are configured, basic authentication is used.

For information on configuring identity assertion providers, see "Configuring the REST Service" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

For more information, see "Configuring Authentication Providers" in Oracle Fusion Middleware Securing Oracle WebLogic Server.