27 Managing REST Services

This chapter provides an overview of managing Oracle WebCenter Portal's REST services in WebCenter Portal applications.

This chapter includes the following sections:

Audience

The content of this chapter is intended for Fusion Middleware administrators (users granted the Admin or Operator role through the Oracle WebLogic Server Administration Console). For more information, see Section 1.8, "Understanding Administrative Operations, Roles, and Tools."

27.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 Portal 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 Portal REST APIs" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.

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

27.2 Performing Required Manual Configurations to Enable REST

The WebCenter Portal REST APIs are not enabled by default. To enable the REST APIs 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 Section 20.2, "Before You Begin: Performing Required Configurations."

27.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"/>

Note:

The security token is not used for authentication or identity propagation.

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 Portal REST APIs" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.

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

Note:

This section illustrates a simple example of setting up a proxy server on Apache. For more detailed information, refer to the Apache Server documentation available at http://httpd.apache.org/docs. You can also use Oracle HTTP Server (OHS) for your proxy server. For more information, see Oracle Fusion Middleware Administrator's Guide for Oracle HTTP Server.

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               /pathname/rest/api/        http://myhost:8888/rest/api/
    ProxyPassReverse        /pathname/rest/api/        http://myhost:8888/rest/api/
    Substitute              s|myhost:8888/rest/api|yourhost/pathname/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/pathname/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.

Developer Tip:

Set the UserDir permissions in httpd.conf to allow users to drop these files in their own public_html directory. For example, you might hit http://host/~yourname/sample.html to access your sample application, and then have the sample application make XHR calls to http://host/rest/api/resourceIndex.

27.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 27.4, "Configuring a Proxy Server," the following two URIs refer to the same server:

http://myhost:8888/rest/api/resourceIndex

http://myhost:8888/pathname/rest/api/resourceIndex

27.6 Using Compression

This section explains techniques for enabling compression on the XML or JSON responses that are returned to the client by the WebCenter Portal 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 Middleware 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.

27.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 Section 29.10, "Configuring the REST Service Identity Asserter."

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

Note:

Users can access the CMIS root anonymously. For more information, see "Security Considerations for CMIS REST APIs" in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.