Skip Headers
Oracle® Application Express Listener Installation and Developer Guide
Release 1.1

Part Number E21058-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF · Mobipocket

3 RESTful APIs and Resource Templates

This section describes how to use Oracle Application Express Listener RESTful Application Programming Interfaces (APIs) to expose data stored in an Oracle database.

Topics:

What is a RESTful API?

Representational State Transfer (REST) is a style of software architecture for distributed hypermedia systems such as the World Wide Web. An API is described as RESTful when it conforms to the tenets of REST. Although a full discussion of REST is outside the scope of this document, a RESTful API has the following characteristics:

About Resource Templates

RESTful APIs are created by configuring resource templates. A resource template is a configuration file that binds a set of Uniform Resource Identifiers (URIs) to a SQL query or anonymous PL/SQL block. The set of URIs is identified by a URI template. A URI template is simple syntax for describing URIs, for example:

people/{userid}

The URI template may contain zero or more parameters (for example, {userid}) which along with the HTTP headers sent with a HTTP request can be bound to parameters in the SQL query or anonymous PL/SQL block.

About Resource Template Administration

To access the Resource Template Administration, go to:

  1. In your Web browser, go to:

    http://<hostname>:<port>/apex/resourceTemplates/
    
  2. Enter your Oracle Application Express Listener Administrator credentials.

    The Oracle Application Express Listener Administration Resource Templates page appears.

The Oracle Application Express Listener Administration Resource Templates page displays a list of the currently defined resource templates and provides buttons to create a new resource template, import resource template definitions, and to export the existing definitions to a zip file.

Topics:

Create a Resource Template

A resource template is a configuration file that binds a set of Uniform Resource Identifiers (URIs) to a SQL query or anonymous PL/SQL block. To create a new resource template, click Add Resource Template. A pre-populated sample resource template displays.

Hover the mouse over a field on the page to see a tooltip that describes the purpose of the field.

About URI Templates

Uniform Resource Identifier (URI) template is a compact syntax for describing a range of URIs. For example, assume the Oracle Application Express Listener is running on a machine named example.com then the URI Template hello?who={person} would match the following URI:

http://example.com/apex/hello?who=World

The literal value World is bound to the URI Template parameter named person.

About URI Template Grammar

Currently there is no standardized URI Template syntax. Oracle Application Express Listener supports a limited subset of the current draft specification. The following grammar rules apply:

  • URI Templates must not start with a slash (/) character.

  • URI Templates can contain any Unicode character.

  • Parameters are declared with the use of curly braces ({})

  • Parameter names must start with an alphabetic character followed by zero or more alphanumeric characters and the characters: underscore (_) or hyphen (-).

  • There is no support for optional parameters.

About the Entity Tag

An entity tag (ETag) is a HTTP Header that acts as a version identifier for a resource. Use ETag headers to avoid retrieving previously retrieved resources and to perform optimistic locking when updating resources.

Oracle Application Express Listener provides three strategies for generating entity tags:

  • Secure Hash - The contents of the returned resource representation are hashed using a secure digest function to provide a unique fingerprint for a given resource version.

  • Query - Manually define a query that uniquely identifies a resource version. Instead of hashing the entire resource representation, only the result of the query is hashed. A manually defined query can often generate an entity tag more efficiently than hashing the entire resource representation.

  • None - Do not generate an entity tag.

About Resource Handlers

A resource handler is a query or an anonymous PL/SQL block responsible for handling a particular HTTP method. Although multiple resource handlers can be defined for a resource template, only one handler per HTTP method is permitted.

Topics:

Add Other Handlers

To add other handlers to a resource template:

  1. Click the Add Handler button.

    The Add HTTP Method Handler dialog box appears.

  2. Choose the HTTP method you wish to implement. See "About Supported HTTP Methods".

  3. Click Add.

    Each resource handler displays as a separate tab identified by the HTTP method that it implements.

About Supported HTTP Methods

The HTTP specification defines several standard methods which are used to operate on a resource. The four most commonly used operations are:

  • GET - Retrieves a representation of a resource

  • POST - Creates a new resource or adds a resource to a collection

  • PUT - Updates an existing resource

  • DELETE - Deletes an existing resource

Strategies When Choosing a Resource Handler Type

Many different strategies are supported for generating representations:

  • Comma Separated Values Query - Executes an SQL and transforms the result set into a CSV representation.

  • Query - Executes an SQL Query and transforms the result set into a JSON (JavaScript Object Notation) representation. A specialization of this strategy, generates a single JSON result. Note that the result is not wrapped in a JSON array.

  • PL/SQL Block - Executes an anonymous PL/SQL block and transforms any OUT or INOUT parameters into a JSON representation.

  • Media Resource - Executes a SQL Query conforming to a specific format and turns the result set into a binary representation with an accompanying HTTP Content-Type header identifying the internet media type of the representation.

About Resource Handler Parameters

Parameters declared in the URI template are implicitly passed to the resource handler. For example if the URI template is people/{userid} then a parameter userid is automatically made available to the resource handler.

Parameters to a resource handler can also be manually defined to bind HTTP headers to the resource handler, or to cast a URI template parameter to a specific data type. For example, a resource handler might need to know the value of the HTTP Accept-Language header in order to localize the generated representation.

To add a parameter:

  1. Click the Add Parameter button.

  2. Specify the following:

    • Name - Enter the name of the parameter as passed to the resource handler (required).

    • Aliasing - Enter the original name of the parameter if you wish to rename a parameter (optional).

    • Source - Enter either the header (that is, the HTTP header) or URI (that is, the parameter from the URI template).

    • Access - IN, INOUT, or OUT. URI Template parameters can only be IN. A value of IN for a header parameter implies the header will be present in the HTTP request. A value of INOUT indicates the value will be present in both the HTTP request and response. A value of OUT indicates the value will only be present in the HTTP response.

    • Type - The primitive data type of the parameter: String, Integer, Double, Boolean, or Long

Tip:

To delete a parameter, select the icon on the immediate right.

Referencing Parameters

You can reference parameters in the resource handler definition by prefixing the parameter name with a colon character, for example:

select 'Hello ' || :person || ' from APEX' greeting from dual

This example causes the :person token to be replaced with the actual value of the person parameter when the resource template is evaluated. Parameter substitution uses the standard Oracle Prepared Statement facilities, so the normal rules apply as to when and where parameters can be placed.

For example the following example is not valid, because the table name cannot be specified using a parameter:

select * from :table where some_id = :id

About Acceptable Media Types

For resource handlers that accept a content body (POST and PUT), you can define what types of content the handler is able to accept by specifying acceptable MIME types in the Acceptable field. You can specify more than one content type by separating types with a comma. You can also specify a wildcard character to accept a range of types, for example:

image/*

About Security Constraints

Resource handlers can define a security constraint to provide a degree of access control. You can specify the following options:

  • None - Any user is allowed access to the resource.

  • Authenticated - A user must be logged in to access the resource.

  • Secure - The resource must be accessed over a secure channel (for example, HTTPS).

  • Secure & Authenticated - User must be logged in and the channel must be secure.

The security constraint can only be applied when the Oracle Application Express Listener is correctly configured to use one of the supported security configurations. For more information, see "About Resource Template Security"

About Resource Handler Types

This section describes supported resource handler types.

Topics:

Query

This resource handler type evaluates the supplied query and turns the resulting rows into a JSON representation. Consider the following example:

select 'Hello ' || :person || ' from APEX' greeting from dual

This example generates a response similar to the following:

{
 "items": [
  {
   "greeting":"Hello World from APEX"
  }
 ]
}

In this example:

  • The Content-Type of the response will be application/json

  • The root the JSON document will be a JSON Object

  • The JSON Object will contain a property named: items

  • The value of the property will be an array

  • Each row in the result set will map to a JSON object

  • Each column in a row will map to a JSON property

  • The column name will always be in lower-case and the case of the value will be preserved

  • If the query has no results, the items property referred to above will just contain an empty array

Since a query can only retrieve data and can never change the state of the database, the Query resource handler can only be used the HTTP GET Method.

With One Result Only

A variation of the Query resource handler enables the production of JSON resources that correspond to a result set with exactly one row, for example:

select * from oe.orders where order_id = :id

This example generates a response similar to:

{
 "order_id":2458,
 "order_date":"2007-08-16T21:34:12.234Z",
 "order_mode":"direct",
 "customer_id":101,
 "order_status":0,
 "order_total":78279.6,
 "sales_rep_id":153
}

If an invalid order_id value is provided then a 404 - Not Found response is generated.

Comma Separated Values Query

This resource handler type is very similar to the Query resource handler except that the results are returned as a comma separated values instead of JSON. Consider the following example:

select * from oe.categories_tab

This example generates a response similar to:

hardware4,memory components/upgrades,14,10
hardware5,"processors, sound and video cards, network cards, motherboards",15,10
...

In this example:

  • Each column is delimited by a comma

  • Each row is delimited by a new line character

  • Columns containing commas or double quotes will be quoted with the double quote character

Media Resource

This resource handler type evaluates a specially structured SQL query and returns the resulting row as a binary representation. The query must follow the following format:

select <content_type>, <content_body> from ... where ...

In this format:

  • The query must return one row and one row only

  • The result set must consist of two columns:

    • The first <content_type> must be a string indicating the internet media type of the representation

    • The second <content_body> must contain the content of the representation. This column must be one of the following types: VARCHAR, CLOB, BLOB, RAW, LONG RAW, or XMLType

Similar to the Query resource handler, the Media resource handler can only be used for the HTTP GET method, since it can only evaluate an SQL Query. This resource handler type is very useful for generating XML and HTML representations.

The following example generates a KML representation of customer locations by state, making it possible to easily share customer location data with GIS applications:

select 'application/vnd.google-earth.kml+xml', xmlquery('
<k:kml xmlns:k="http://www.opengis.net/kml/2.2">
<k:Folder>
 <k:name>{$state}</k:name>
{ for $c in ora:view("oe","customers")/ROW
  let $loc := $c/CUST_GEO_LOCATION/SDO_POINT
  where $c/CUST_ADDRESS/STATE_PROVINCE = $state
  return
  <k:Placemark>
   <k:name>{concat($c/CUST_FIRST_NAME," ",
$c/CUST_LAST_NAME)}</k:name>
   <k:Point>
     <k:coordinates>{$loc/X/text()},
{$loc/Y/text()},0</k:coordinates>
   </k:Point>
 </k:Placemark>
}
</k:Folder>
</k:kml>' passing :state as "state" returning content) from dual

PL/SQL Block

This resource handler type evaluates the supplied PL/SQL block and turns any outbound parameters into a JSON representation. This resource handler type is typically used to service HTTP POST,PUT and DELETE operations. This handler has several features aimed at increasing ease of use, including:

  • When a HTTP request includes a content body, two parameters named :contentType and :body are automatically passed to the handler. The former provides the Content-Type of the request and the latter provides the content body of the request as a BLOB.

  • When the HTTP request includes a content body with a Content-Type of application/x-www-form-urlencoded, the body is automatically parsed and each field in the form is converted to a parameter passed to the handler.

  • The PL/SQL block can indicate the HTTP Status code using the X-APEX-STATUS-CODE response header.

  • The PL/SQL block can indicate the location of the updated resource using the X-APEX-FORWARD response header.

For example, suppose you have a Resource Template with the following definition:

  • URI Template - gallery/

  • HTTP Method - POST

  • Handler Type - PL/SQL Block

Assume the following parameters are defined:

Name Aliasing Source Access Type
name Slug Header IN String
status X-APEX-STATUS-CODE Header OUT Integer
location X-APEX-FORWARD Header OUT String

Assume the following PL/SQL block is defined:

declare
begin
 insert into scott.gallery values(:name,:contentType,:body);
  :status := 201;
  :location := 'gallery/' || :name;
end;

The above handler inserts the supplied image into the scott.gallery table, returns the location of the stored image, and indicates the operation created a new resource. Note the following:

  • The :contentType and :body parameters are automatically passed to the handler. You do not need to define them manually.

  • You must manually define the :name parameter to map it from the Slug header.

  • The :status parameter is mapped to the X-APEX-STATUS-CODE header as an Integer. The value of 201 is specified by HTTP to indicate a new resource was created.

  • The :location parameter is mapped to the X-APEX-FORWARD header.

    When the Oracle Application Express Listener sees this header in the response, it abandons generating a JSON representation of the outbound parameters and attempts to return a representation of the indicated location.

    Note that this example assumes that there is a separately defined Resource Template that retrieves resources of the form gallery/<name>.

Example: Creating an Image Gallery

This example builds an image gallery that displays thumbnails of all images and upload new images. Additionally, this example creates a Web application suitable for use with modern Web browsers and a RESTful API for non-browser-based clients.

Topics:

Before You Begin

This section describes some common conventions used in this example as well as best practices regarding API entry points.

Topics:

About URIs

Throughout this example, URIs and URI Templates are referenced using an abbreviated form that omits the host name and context path. Consider the following example:

gallery

To access this URI in your Web browser, you would use a URI in the following format:

http://<host>:<port>/apex/gallery

Where:

  • <host> is the host on which the Oracle Application Express Listener is running.

  • <port> is the port on which the Oracle Application Express Listener is running.

  • apex is the Web application context where the Oracle Application Express Listener is deployed.

About API Entry Points

In RESTful designs it is a best practice to have only one well known entry point. This minimizes the hard-coded footprint of the API, making it much easier to evolve the API over time. In this example, the entry point of our application will be a URI named:

gallery

This URI will provide a HTML representation that:

  • Enumerates all the images in the gallery. For each image, you must know:

    • The URI of the image

    • The title of the image

  • Provides a link to the URI to which to post new images

  • Provides a link to an alternate JSON representation of the gallery that includes all the information above

Create a Database Schema

First, create two tables and two sequences to store the image gallery data. Note this exercise assumes that you have configured Oracle Application Express Listener to connect to the database using apex_public_user.

Execute the following scripts as the database user, scott.

create sequence gallery_seq;
/
grant select on gallery_seq to apex_public_user;
/
create table gallery (image_id number, title varchar2(1000),
content_type varchar2(1000), image blob);
/
grant all on gallery to apex_public_user;

Upload Images

This gallery URI functions as the endpoint to which clients can submit new images. The upload facility should be able to accept requests containing the actual image data and also requests containing multipart form-data (as generated by HTML forms).

To build the upload features:

  1. Create a new Resource Template with the following data:

    • URI Template - gallery

    • HTTP Method - POST

    • Handler Type - PL/SQL Block

  2. Manually define the following parameters:

    Name Aliasing Source Access Type
    title Slug Header IN String
    status X-APEX-STATUS-CODE Header OUT Integer
    location X-APEX-FORWARD Header OUT String

  3. Define the following PL/SQL block:

    declare
     image_id integer;
    begin
     select scott.gallery_seq.nextval into image_id from dual;
     insert into scott.gallery
      values(image_id,:title,:contentType,:body);
     :status := 201;
     :location := 'gallery/' || image_id;
    end;
    

    Note that the:

    • PL/SQL block assigns a unique id to the image (image_id) and inserts the image data, image title, and image content type into the scott.gallery table.

    • Block returns a 201 status which indicates a new resource has been created.

    • Block indicates the location of the created resource is of the form gallery/<imageid>.

  4. Once you create the Resource Template, save it, and proceed to the next step.

Create an Image Upload Form

To invoke the previously defined image upload handler, you need a HTML form that enables users to specify the image to upload.

To create an upload form:

  1. Create a new Resource Template with the following data:

    • URI Template - upload

    • HTTP Method - GET

    • Handler Type - Media Resource

  2. Include the following SQL Query:

    select 'text/html',
     '<html>
     <head>
      <title>Choose Image to Upload</title>
     </head>
     <body>
     <div>
      <h1>Choose Image to Upload</h1>
      <form action="gallery"
           enctype="multipart/form-data"
           method="post">
      <label for="title">Title</label>
      <input type="text" id="title" name="title"><br/>
      <label for="file">File</label>
      <input type="file" id="file" name="file"><br/>
      <div class="buttons">
        <button type="submit" class="button">Upload</button>
        <a href="gallery" class="button">Cancel</a>
      </div>
      </form>
    </div>
    </body>
    </html>' from dual
    

    Note that:

    • This illustrates a simple way to generate static text resources using Oracle Application Express Listener. Notice that the first column in the query is mapped to the content type of the resource and the second column becomes the body of the resource.

    • Oracle does not typically recommend this approach since the SQL literal strings cannot be very big and it involves a database round-trip for data that is not actually retrieved from the database.

      Instead, Oracle recommends having your Web application serve static resources directly.

    • This form contains two fields. The first indicates the image title and the second the image content

  3. When you have created the Resource Template, try it in your browser. Enter a URL with the format:

    http://<host>:<port>/apex/upload
    

    Try choosing an image, giving it a title, and uploading it.

    When you click the Upload button, the browser should result in a 404 Not Found error. Remember that the POST handler you configured tells the Web browser to redirect to a gallery/<imageid> URI which you have not yet defined. However the image data will be stored in the scott.gallery table.

Display the Image

To display the image:

  1. Create a new Resource Template with the following data:

    • URI Template - gallery/image/{imageid}

    • HTTP Method - GET

    • Handler Type - Media Resource

  2. Manually define the following parameters:

    Name Aliasing Source Access Type
    imageid   URI IN Integer

  3. Include the following SQL Query:

    select content_type, image from scott.gallery where image_id =
    :imageid
    

    Note that this query retrieves the content type and image data for the specified image.

Display the Gallery

To display the gallery:

  1. Open the gallery Resource Template and add the following data for a GET resource handler:

    HTTP Method GET
    Handler Type Media Resource

    This will enable you to display the data stored in the gallery.

  2. Include the following SQL Query:

    select 'text/x-apex-html', xmlquery('
    <html>
     <head>
     <link rel="alternate" type="application/json" href="gallery?alt=json"/>
     </head>
     <body>
      <h1>Image Gallery</h1>
      <div class="buttons">
       <a href="upload" >Upload Image</a>
      </div>
      <div>
        <span itemscope="itemscope"><a itemprop="gallery"
    href="./gallery"/></span>
       <ol id="images">
        {
        for $i in ora:view("scott","gallery")/ROW
        order by $i/IMAGE_ID descending
        return
         <li itemscope="itemscope">
          <a href="./gallery/{$i/IMAGE_ID/text()}">
           <img itemprop="image" src="./gallery/images/
    {$i/IMAGE_ID/text()}"/>
           <div itemprop="title">{$i/TITLE/text()}</div>
          </a>
         </li>
        }
       </ol>
      </div>
      <br/>
     </body>
    </html>
    ' returning content) from dual
    

    Note that the:

    • Media resource handler is used to define a HTML resource and the HTML is generated dynamically using the xmlquery() SQL function.

    • Content type of the resource is specified as text/x-apex-html. This is an Oracle Application Express specific content type. When Oracle Application Express Listener encounters this content type it expects the content of the resource to be well formed XML. It then transforms this XML into HTML.

    • Generated HTML includes a link to an alternate JSON representation of the gallery data:

      <link rel="alternate" type="application/json"
      href="gallery?alt=json"/>
      

      This representation is automatically generated by Oracle Application Express Listener using its capability to transform HTML marked up with Microdata into JSON.

      For each image in the gallery a <li> element is generated. The <li> element is marked up with Microdata to assist clients in extracting the gallery data from the HTML. Microdata is a feature of HTML5 enabling structured semantic data to be interwoven into HTML documents. This semantic data can be easily and reliably parsed by clients.

  3. When you have updated the Resource Template go ahead and try it. In your Web browser, enter a URL using the format:

    http://<host>:<port>/<apex>/gallery
    

    You should see the image you previously uploaded.

Improve the Appearance of the Gallery

Next, create some JavaScript and CSS resources to improve the appearance of the gallery.

Topics:

Create gallery.css

To create gallery.css:

  1. Create a new Resource Template with the following data:

    • URI Template - gallery.css

    • HTTP Method - GET

    • Handler Type - Media Resource

  2. Include the following SQL Query:

    select 'text/css', '
    html { font-size: 100%; }
    body { font-size: 1em; font-family: Arial, Helvetica, sans-serif; 
    background : #e2e1e1; margin-left: 3em; margin-right: 3em;}
    h1, h2, h3, h4, label { text-shadow: 0px 1px 0px #e5e5ee;}
    h1 { text-align: center;}
    a img { border:none; }
    
    #images { margin: 1em auto; width: 100%; }
    #images li { display: inline; }
    #images a { background: #fff; display: inline; float: left;margin: 0 0 27px 30px; width: auto; padding: 10px 10px 15px; textalign:center; text-decoration: none; color: #333; font-size:18px; -webkit-box-shadow: 0 3px 6px rgba(0,0,0,.25); -moz-boxshadow:0 3px 6px rgba(0,0,0,.25); -webkit-transform: rotate(-2deg); -webkit-transition: -webkit-transform .15s linear; -moztransform:rotate(-2deg); }
    #images img { display: block; width: 190px; margin-bottom: 12px; }
    #images li:nth-child(3n) a { -webkit-transform: none; position:relative; top: -5px; -moz-transform: none; }
    
    #images li:nth-child(3n) a { -webkit-transform: none; position:
    relative; top: -5px; -moz-transform: none; }
    #images li:nth-child(5n) a { -webkit-transform: rotate(5deg);
    position: relative; right: 5px; -moz-transform: rotate(5deg); }
    #images li:nth-child(8n) a { position: relative; right: 5px; top:
    8px; }
    #images li:nth-child(11n) a { position: relative; left: -5px; top:
    3px; }
    #images li.messy a { margin-top: -375px; margin-left: 160px;
    -webkit-transform: rotate(-5deg); -moz-transform: rotate(-5deg); }
    #images li a:hover { -webkit-transform: scale(1.25); -moztransform:
    scale(1.25); -webkit-box-shadow: 0 3px 6px
    rgba(0,0,0,.5); -moz-box-shadow: 0 3px 6px rgba(0,0,0,.5);
    position: relative; z-index: 5; }
    .buttons { float: right; margin-top: 1em; margin-bottom: 1em; }
    label {font-weight: bold; text-align: right;float: left; width:
    120px; margin-right: 0.625em; }
    label :after {content(":")}
    input, textarea { width: 250px; margin-bottom: 5px;textalign:
    left}
    textarea {height: 150px;}
    br { clear: left; }
     ' from dual
    

    This style sheet transforms the numbered list of images into a series of thumbnails. It uses some modern CSS features such as transforms and shadows which will not work on older Web browsers.

  3. When you have created the Resource Template edit the gallery Resource Template and add the following in the <head> section:

    <link rel="stylesheet" href="gallery.css" type="text/css"/>
    
  4. Save your changes and view the gallery again using a URL in the format:

    http://<host>:<port>/apex/gallery
    

Create gallery.js

To create gallery.js:

  1. Create a new Resource Template with the following data:

    • URI Template - gallery.js

    • HTTP Method - GET

    • Handler Type - Media Resource

  2. Include the following SQL Query:

    select 'application/javascript', '
    $(function() {
     $(".buttons a").button();
     $(".buttons button").button();
    });
    ' from dual
    

    This script uses the JQuery UI framework to transform the Upload Image link to a clickable button.

About the RESTful API

The previous example created both a Web application and a RESTful API. This section explores the RESTful API.The structured semantic data that clients need to interact with the API is encoded in the HTML as microdata. Clients have two choices for processing this microdata, they can either:

  • Parse it directly from the HTML (browser-based applications will be able to use the HTML5 Microdata JavaScript APIs)

  • Process the alternate JSON representation that Oracle Application Express Listener generates automatically

The alternate representation is identified by the <link> element in the <head> section of the gallery resource. The link element has a rel attribute with the value alternate and a type attribute of application/json.

Consider the following example:

{
 "items": [
  {
   "properties": {
    "gallery": ["http://localhost:8080/apex/gallery"]
   }
  },
  {
    "properties": {
     "image": ["http://localhost:8080/apex/gallery/images/13"],
     "title": ["Cherries"]
  }
 },
...
 {
   "properties": {
    "image": ["http://localhost:8080/apex/gallery/images/4"],
    "title": ["Bay"]
    }
   }
  ]
 }

To successfully navigate the API, clients need the following information:

  • The location of an image is indicated by the image property

  • The title of an image is indicated by the title property

  • New Images can be uploaded by posting data to the URI indicated by the gallery property.

Note that the client only knows about a single URI (gallery) and discovers all other URIs from this initial URI. It does not know anything about the structure of the URIs. It only knows the names of properties that identify certain link types. As the application evolves, the URIs are free to change and clients will not be affected.

About Resource Template Security

Oracle Application Express Listener supports two mechanisms for securing access to Resource Templates:

When you configure either of these two options, Oracle Application Express Listener can honor any Security Constraint values specified in the Resource Template. Note that the identity of the authenticated user is available to the Resource Template using the X-APEX-USER header that is passed with the request.

Topics:

Integration with Oracle Single Sign On

When you correctly configure a supported JEE application container (for example, WebLogic or OC4J) to integrate with Oracle Single Sign On (OSSO), Oracle Application Express Listener attempts to determine the authenticated user identity using the Proxy-Remote-User header that mod_osso provides to the JEE application container. In addition the Oracle Application Express Listener produces a dynamic authentication request which causes the client to be redirected to the single sign on page if the user credentials are missing.

Since Oracle Application Express Listener is trusting a HTTP header (Proxy-Remote-User) to assert the user identity, you must configure Oracle Application Express Listener to only accept requests from the HTTP proxy where mod_osso is deployed. To accomplish this task, add the following line to the apex-config.xml configuration file:

<entry key="apex.security.trustedProxies">ossoproxy.example.com</entry>

In this example, osso-proxy.example.com is the hostname of the server that forwards requests to Oracle Application Express Listener.

External Authentication Using Apache JServ Protocol

When running Oracle Application Express Listener in embedded mode, you can configure it to listen using the Apache JServ Protocol (AJP) protocol instead of HTTP. The AJP protocol has the capability to propagate a user identity. For example, you can configure an Apache HTTPD instance to perform user authentication and to communicate with Oracle Application Express Listener using mod_jk. This means that Resource Templates can be protected with any of the many authentication solutions available to Apache HTTPD.

Example: Protecting Gallery Uploads

You can reconfigure the Gallery's Resource Templates to require users be authenticated before they can upload images to the gallery. This will protect both the upload Resource Template and the POST handler of the gallery Resource Template.

Topics:

Protect Upload Form

To protect the upload form:

  1. Edit the upload Resource Template.

  2. Change the Security Constraint of the GET handler to Authenticated.

  3. Click Save.

Protect Gallery POST Handler

To protect the gallery POST handler:

  1. Edit the gallery Resource Template.

  2. Change the Security Constraint of the POST handler to Authenticated.

  3. Click Save.

Test the Changes

Tip:

This section assumes you are running Oracle Application Express Listener on a JEE Application Container with OSSO configured.

To test the changes:

  1. In your Web browser go to:

    http://<host>:<port>/apex/gallery link
    
  2. Click Upload Image.

    The Oracle Single Sign On page appears.

  3. Enter your credentials.

    The Upload page appears.