Oracle REST Data Services Administration

Administration
  Global Settings
    Connections
      JDBC
    PL/SQL Gateway User
    Security
      Allowed Procedures
      Blocked Procedures
      Validation Function
      Virus Scanning
    Cache Files
      Caching
    Environment
      Error Reporting
      Log Reporting
      Pre-Processing
      Post-Processing
    Excel
  Database Settings
    <database-name>
      Connections
        JDBC
        URL Mapping (Database Settings only)
      Oracle REST Data Services Public User (Database Settings Only)
      PL/SQL Gateway User
      APEX REST Users (Database Settings only)

Connections

Use Connections to specify the connection type: Basic, TNS, or Advanced. (For information about connection types, see Create/Edit/Select Database Connection, especially for the Oracle tab.)

JDBC

Use JDBC to configure JDBC options.

JDBC Driver Type: thin or oci8.

Initial Pool Size: Initial pool size for the number of connections that will be created.

Maximum Statements: Maximum number of statements to cache for each connection.

Connection Size: Maximum and Minimum number of connections.

Inactivity Timeout: How long (in seconds) an available connection can remain idle before it is closed.

Abandoned Connection Timeout: How long (in seconds) a borrowed (in use) connection can remain unused before it is considered as abandoned and reclaimed.

URL Mappings (Database Settings only)

URL mapping is used in configuring multiple database connections, to define the rules for how requests are routed to the appropriate database.

Specify the rules in the Rule Type and the Routing Rule to your database connection. You can use regular expressions in the Routing Rule.

To add a mapping, click the Add URL (+) icon, select the Rule Type, and specify the Routing Rule. To delete a mapping, select it and click the Remove URL (X) icon.

Rule Type: Type of rule: Request Path, URL Path, or Regular Expression.

Routing Rule: Rule on how to route the request to your database connection. See the examples or routing rules in this topic.

Schema for RESTful Services (optional): The name of the Application Express workspace where RESTful services are defined in the database connection. This can be omitted if RESTful Services are not being used.

Example of routing rules:

URL = http://example.com/apex/sales/f?p=1:1

• Protocol: http

• Host name: example.com

• Context root: /apex (location at which the REST Data Services is deployed on the application server)

• Request path: /sales/f?p=1.1 (the request URL relative to the context root)

Example of routing rule using request path prefix:

Assuming REST Data Services is deployed on example.com, its context path is /apex, and your database setting name is sales_prod, you can create the following request path prefix routing rule:

• Rule Type: Request Path

• Routing Rule: /sales

• Schema for RESTful Services: sales_rest

The preceding rule means that any requests matching: http://example.com/apex/sales/... will be routed to the sales_prod database connection. The sales_rest schema, specified in the sales_prod database connection, will be searched for RESTful Services definitions.

The preceding routing rule will match any of the following requests:

http://example.com/apex/sales/f?p=1:1
https://example.com/apex/sales/f?p=1:1
http://example.com/apex/sales/leads/
http://www.example.com/apex/sales/forecasting.report?month=jan  (if www.example.com resolves to the same system)

The preceding routing rule will not match any of the following requests:

http://example.com:/apex/leads/f?p=1:1  (missing the /sales prefix)
http://example.com/apex/f?p=1:1  (missing the /sales prefix)
http://example.com/pls/sales/leads/  (the context root is wrong)

Example of routing rule using URL prefix:

Assuming REST Data Services is deployed on example.com, its context path is /apex, and your database setting name is sales_prod, you can create the following URL prefix routing rule:

• Rule Type: URL Path

• Routing Rule: http://example.com/apex/sales

• Schema for RESTful Services: sales_rest

The preceding rule means that any requests matching: http://example.com/apex/sales/... will be routed to the sales_prod database connection. The sales_rest schema, specified in the sales_prod database connection, will be searched for RESTful Services definitions.

The preceding routing rule will match any of the following requests:

http://example.com/apex/sales/f?p=1:1
http://example.com/apex/sales/leads/
http://example.com/apex/sales/forecasting.report?month=jan

The preceding routing rule will not match any of the following requests:

https://example.com/apex/sales/f?p=1:1  (the protocol is wrong)
http://example.com:8080/apex/sales/f?p=1:1  (the port is wrong)
http://example.com/apex/f?p=1:1  (missing the /sales segment of the base URL)
http://example.com/pls/sales/leads/  (the context root is wrong)
http://www.example.com/apex/sales/forecasting.report?month=jan  (the host name is wrong)

Oracle REST Data Services Public User (Database Settings Only)

Specify credentials (user name and password) for the Oracle REST Data Services public user (the database user that has privileges to access the Oracle REST Data Services RESTful services).

PL/SQL Gateway User

Specify credentials (user name and password) for the PL/SQL Gateway user, which is responsible for executing stored PL/SQL stored packages and procedures on the specified database connection.

APEX REST Users (Database Settings only)

If you want to be able to use the Oracle Application Express RESTful services, specify the password for the database user APEX_REST_PUBLIC_USER, which used when invoking PL/SQL Gateway operations, and for the database user APEX_LISTENER, which is used to query RESTful services definitions stored in Oracle Application Express.

Specifying these users enables Oracle Application Express applications to publish web services that are accessed by other applications to exchange data. For example, you can configure a RESTful service to return all employee names for a particular department. The data exchange for a RESTful service follows the Representational State Transfer (REST) protocol. See REST Development and Oracle Application Express Application Builder User's Guide for information on how to develop RESTful services for use with REST Data Services.

Security

Security settings are used to validate procedure requests and determine if a user is allowed to access the procedure.

Verify Secure Socket Layer Requests: Enable this option if HTTPS is available in your environment.

A RESTful service can be protected with the OAuth2 protocol to control access to non-public data. OAuth2 requires all requests involved in the OAuth2 authentication process to be transported via HTTPS. The default behavior of REST Data Services is to verify that all OAuth2 related requests have been received via HTTPS. It will refuse to service any such requests received over HTTP, returning an HTTP status code of 403 Forbidden.

Disabling this option should only be used for development or test environments. Do not disable this option for production environments because it will result in user credentials being passed in clear text.

Security Cache: When you specify a PL/SQL validation function, Oracle REST Data Services uses the security cache to cache the procedures names and determine if they are valid or invalid. Using a caching mechanism reduces the number of database round-trips needed to execute the PL/SQL Validation Function.

Maximum Cache Entries: Maximum cache size. When the maximum entries have been reached, the older (or stale) procedure name that was least recently used is removed from the cache and a new procedure name is added to the cache.

Allowed Procedures

Specify patterns for procedures, packages, or schema names that are allowed to be directly executed from a browser. You can use an asterisk (*) to substitute zero or more characters, and a question mark (?) to substitute for any one character.

A benefit of specifying allowed procedures is that the procedure names and procedure patterns are stored in Oracle REST Data Services. By contrast, invoking the PL/SQL validation function requires a database round-trip.

To add an entry, click the Add Procedure (+) icon and enter the pattern. To delete an entry, select it and click the Remove Procedure (X) icon.

If no allowed procedures are specified, Oracle REST Data Services does not validate the procedure names to determine if the procedure is allowed for processing.

Blocked Procedures

Specify patterns for procedures, packages, or schema names that are forbidden be directly executed from a browser. You can use an asterisk (*) to substitute zero or more characters, and a question mark (?) to substitute for any one character.

If no blocked procedures are specified, Oracle REST Data Services does not validate the procedure names to determine if the procedure is blocked from processing

To add an entry, click the Add Procedure (+) icon and enter the pattern. To delete an entry, select it and click the Remove Procedure (X) icon.

Disable Default Internal Exclusion List: If option is selected, the Oracle REST Data Services internal exclusion list is not enforced. This internal exclusion list blocks users from accessing the following:

sys.*, dbms_*, utl_*, owa_*, owa.*, htp.*, htf.*, wpg_docload.*

Oracle recommends that you not select this option; that is, do not disable the default internal exclusion list. The only possible exception is temporarily disabling the internal exclusion list for debugging purposes.

Validation Function

You can use the Validation Function to determine if the requested procedure in the URL should be allowed for processing. Oracle REST Data Services executes the validation function you specify for each requested procedure, or checks the security cache to determine if a procedure is valid or invalid.

The validation function returns true if the procedure is allowed for processing. Otherwise, it returns false.

Validation Function Type: Implementation language: PL/SQL or JavaScript.

Validation Function: For PL/SQL, the name of the stored function that resides in the database. If the validation function you specify does not exist, an error message is displayed.

For JavaScript, the code written in JavaScript. The advantage of using JavaScript instead of using the PL/SQL database function is that there are not any database round-trips to execute the validation function.

Virus Scanning

Specify the Internet Content Adaptation Protocol (ICAP) Server name and Port for virus-scanning of your files. A message is displayed if a file is infected.

Cache Files

Specify procedure names to allow caching of files.

To add an entry, click the Add Procedure (+) icon and enter the procedure. To delete an entry, select it and click the Remove Procedure (X) icon.

Keep most recently used files: If selected, files that are most recently used will remain in the cache. Specify the maximum number of files to cache. When the maximum entries have been reached, the older files are removed from the cache when a new file is added

Keep files for the specified duration: If selected, files that are cached expire after the specified number of days, hours, or minutes (must be greater than 0).

Caching

Cache File Location: Directory for the cache files.

Environment

Application Express Document Table: Name of the document table used by Application Express. (All files uploaded using the PL/SQL Gateway are stored in a document table.)

PL/SQL Gateway

Default Web Page: Default web page to display.

Extension Classes: Extension classes to extend REST Data Services.

Procedure Recorder: If selected, causes procedures to be logged.

Error Reporting

You can specify to show debug messages on the console: or to show error messages in a browser, or to do both or neither. On production systems, you should leave both options unselected (disabled).

Show debug messages on console: If selected, displays debug messages on the console. This may help with problem diagnosis and is appended to the REST Data Services log output. However, you should not enable this option on production systems due to the performance impact of outputting large amounts of data to the log.

Show error messages on browser: If selected, displays error responses in the browser, including for each a detailed error message and a stack trace. However, do not enable this option on productions systems due to the risk of sensitive information being revealed.

Log Reporting

Logging: Specifies whether to make entries in the Oracle REST Data Services log. The log includes activities such as adding a procedure to the cache, finding a procedure in the cache, or reloading a procedure. The log displays the database time and processing time in milliseconds for that procedure.

Keep most recent log messages: If selected, entries that are most recent will remain in the log. Specify the maximum number of log messages to cache. When the maximum entries have been reached, the older log messages are removed from the cache when a new log message is added.

Pre-Processing

Specify the names of procedures to be executed before executing the requested procedure.

To add an entry, click the Add Procedure (+) icon and enter the procedure name. To delete an entry, select it and click the Remove Procedure (X) icon.

Post-Processing

Specify the names of procedures to be executed after executing the requested procedure.

To add an entry, click the Add Procedure (+) icon and enter the procedure name. To delete an entry, select it and click the Remove Procedure (X) icon.

Excel

If you are using Oracle Application Express, you have the option of placing your Excel files into an Application Express collection.

Process Excel files into a collection: If selected, puts Excel files into an Application Express Collection.

Put each Excel worksheet into one collection: If selected, puts all Excel worksheets into a single collection, for which you specify the Collection Name.

Use the name of the Excel worksheet as the collection name: If selected, creates a collection for each Excel worksheet, and uses each worksheet name for the corresponding collection name.