Skip Headers
Oracle® REST Data Services Installation and Configuration Guide
Release 2.0

E25066-10
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
PDF · Mobi · ePub

2 Configuring Oracle REST Data Services

This section explains how to configure Oracle REST Data Services 2.0 for connecting to multiple databases for routing requests, and refers users to other documentation sources for other configuration information.

Tip:

Oracle REST Data Services must be restarted after making configuration changes. See your application server documentation for information on how to restart applications.

Topics:

2.1 Configuring Multiple Databases

Oracle REST Data Services supports the ability to connect to more than one database. This section describes different strategies for routing requests to the appropriate database.

Topics:

2.1.1 About the Request URL

Oracle REST Data Services supports a number of different strategies for routing requests to the appropriate database. All of these strategies rely on examining the request URL and choosing the database based on some kind of match against the URL. It is useful to recap the pertinent portions of a request URL, consider the following URL:

https://www.example.com/ords/sales/f?p=1:1

This URL consists of the following sections:

  • Protocol: https

  • Host Name: www.example.com

  • Context Root: /ords

    The context root is the location at which Oracle REST Data Services is deployed on the application server.

  • Request Path: /sales/f?p=1.1

    This is the portion of the request URL relative to the context root.

For different applications, it may be important to route requests based on certain prefixes in the request path or certain prefixes in the full request URL.

There are two steps to configuring multiple databases:

  1. Configuring the database connection information.

  2. Configuring which requests are routed to which database.

2.1.2 Configuring Additional Databases

When you first configure Oracle REST Data Services, you configure a default database connection named: apex. You can create additional database connections using the setup command.

Tip:

To see full help for the setup command type:
java -jar ords.war help setup

To create a database connection type the following:

java -jar ords.war setup --database <database name>

Where:

  • <database name> is the name you want to give the database connection.

You are prompted to enter the information required to configure the database. See Section 1.4, "Configuring Oracle REST Data Services" for more information on the data that must be entered.

Once you have configured the additional databases proceed to the next step to define the rules for how requests are route to the appropriate database.

2.1.3 Routing Based on the Request Path Prefix

You create request routing rules using the map-url command.

Tip:

To see full help for the setup command type:
java -jar ords.war help map-url

If you want to route requests based just on matching a prefix in the request path portion of the URL, use the map-url command as follows:

java -jar ords.war map-url --type base-path --workspace-id <workspace name> <path prefix> <database name>

Where:

  • <workspace name> is the name of the Oracle Application Express workspace where RESTful services for this connection are defined. This may be omitted if RESTful Services are not being used.

  • <path prefix> is the prefix that must occur at the start of the request path.

  • <database name> is the name of the database connection configured in the previous step, Section 2.1.2, "Configuring Additional Databases".

2.1.3.1 Example:

Assume Oracle REST Data Services is deployed on a system named example.com at the context path: /ords, then create the following rule:

java -jar ords.war map-url --type base-path --workspace-id sales_rest /sales sales_db

This rule means that any requests matching http://example.com/ords/sales/... are routed to the sales_db database connection. The sales_rest workspace defined within the sales_db database is searched for RESTful Services definitions.

The previous rule matches all of the following requests:

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

The previous rule does not match of any of the following requests:

https://example.com/ords/sales/f?p=1:1  (The protocol is wrong.)
http://example.com:8080/ords/sales/f?p=1:1  (The port is wrong.)
http://example.com/ords/f?p=1:1  (Missing the /sales prefix.)
http://example.com/pls/sales/leads/  (The context root is wrong.)

2.1.4 Routing Based on Request URL Prefix

If you want to route requests based on a match of the request URL prefix, use the map-url command as follows:

java -jar ords.war map-url --type base-url --workspace-id <workspace name> <url prefix> <database name>

Where:

  • <workspace name> is the name of the Oracle Application Express workspace where RESTful services for this connection are defined. This may be omitted if RESTful Services are not being used.

  • <url prefix> is the prefix with which the request URL must start.

  • <database name> is the name of the database connection.

2.1.4.1 Example:

Assume Oracle REST Data Services is deployed on a system named example.com at the context path: /ords, then create the following rule:

java -jar ords.war map-url --type base-url --workspace-id sales_rest http://example.com/ords/sales sales_db

This rule means that any requests matching http://example.com/ords/sales/... are routed to the sales_db database connection. The sales_rest workspace defined within the sales_db database is searched for RESTful Services definitions.

The previous rule matches all of the following requests:

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

The previous rule does not match of any of the following requests:

https://example.com/ords/sales/f?p=1:1  (The protocol is wrong.)
http://example.com:8080/ords/sales/f?p=1:1  (The port is wrong.)
http://example.com/ords/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/ords/sales/forecasting.report?month=jan  (The host name is wrong.)

2.2 Configuring Security, Caching, Pre and Post Processing, Environment, and Excel Settings

To configure security, caching, pre-post processing, environment, and Excel settings, see Section 1.4.4, "Using SQL Developer Oracle REST Data Services Administration (Optional)".

2.3 Developing RESTful Services for Use with Oracle REST Data Services

For more information on how to develop RESTful Services for use with Oracle REST Data Services, see "Using RESTful Services" in Oracle Application Express SQL Workshop Guide.