1 Installing Oracle REST Data Services

Oracle REST Data Services supports the following Java EE application servers:

Oracle REST Data Services system requirements are as follows:

• Oracle Database (Enterprise Edition, Standard Edition or Standard Edition One) release 11.1 or later, or Oracle Database 11g Release 2 Express Edition.

• Java JDK 1.7 or later.

• Web browser requirements:

  • Microsoft Internet Explorer 8.0 or later.

  • Mozilla Firefox 3.0 or later.

  • Google Chrome 2.0 or later.

To install Oracle REST Data Services:

1. Download, install, and configure Oracle REST Data Services.

2. Deploy Oracle REST Data Services. Deployment options include:

   • Standalone Mode.

   • Oracle WebLogic Server.

   • GlassFish Server.

   • Apache Tomcat.

Oracle REST Data Services provides several command line commands. For example, you can configure the location where Oracle REST Data Services stores configuration files, configure the database Oracle REST Data Services uses, and start Oracle REST Data Services in standalone mode.

To display a full list of available commands, go to the directory or folder containing the ords.war file and execute the following command:

java -jar ords.war help

A list of the available commands is displayed. To see instructions on how to use each of these commands, enter help followed by the command name, for example:

java -jar ords.war help configdir

Oracle REST Data Services uses the following database users:

The APEX_<xxx> users are created during the Oracle Application Express installation process.

As part of the Oracle REST Data Services installation, privileges are granted to several users:

• PUBLIC is granted SELECT on many ORDS_METADATA tables and views.

• PUBLIC is granted EXECUTE on PL/SQL packages that are available for users to invoke.

• ORDS_METADATA is granted EXECUTE on the following:

  • SYS.DBMS_ASSERT

  • SYS.DBMS_CRYPTO

  • SYS.DBMS_LOB

  • SYS.DBMS_OUTPUT

  • SYS.DBMS_REGISTRY

  • SYS.DBMS_SESSION

  • SYS.DBMS_UTILITY

  • SYS.VALIDATE_ORDS

  • SYS.HTF

  • SYS.HTP

  • SYS.OWA

  • SYS.WPG_DOCLOAD

• ORDS_METADATA is granted SELECT on the following:

  • SYS.DBA_DIRECTORIES

  • SYS.DBA_OBJECTS

• ORDS_METADATA is granted the following system privileges:

  • ALTER USER

  • CREATE TRIGGER

• ORDS_METADATA is granted the necessary object privileges to migrate Application Express REST data to ORDS_METADATA tables.

The procedures in this topic apply to installing Oracle REST Data Services in a traditional (non-CDB) database. If you want to install and use Oracle REST Data Services in a multitenant database environment, see Using the Multitenant Architecture with Oracle REST Data Services section.

To install and configure Oracle REST Data Services:

1. Download the file ords.version.number.zip from the Oracle REST Data Services download page.

   Note that the version.number in the file name reflects the current release number.

2. Unzip the downloaded zip file into a directory (or folder) of your choice:

   • UNIX and Linux: unzip ords.version.number.zip

   • Windows: Double-click the file ords.version.number.zip in Windows Explorer

3. Choose one of the following installation options:

   • Simple Installation Using Parameters File.

   • Advanced Installation Using Command-Line Prompts.

4. You can reinstall or uninstall Oracle REST Data Services if required.

This section describes how to use Oracle SQL Developer to administer Oracle REST Data Services.

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

This default behavior can be disabled in environments where HTTPS is not available as follows:

1. Locate the folder where the Oracle REST Data Services configuration is stored.

2. Edit the file named defaults.xml.

3. Add the following setting to the end of this file just before the </properties> tag.

   <entry key="security.verifySSL">false</entry>
   

4. Save the file.

5. Restart Oracle REST Data Services if it is running.

Note that it is only appropriate to use this setting in development or test environments. It is never appropriate to use this setting in production environments because it will result in user credentials being passed in clear text.

1. To start Standalone mode, execute the following command:

   java -jar ords.war standalone
   

   If you have not yet completed the standalone configuration, you are prompted to do so.

   Tip:

   To see help on standalone mode options, execute the following command:

   java -jar ords.war help standalone
   

   Note:

   If you want to use RESTful services that require secure access, you should use HTTPS.

2. When prompted, specify the location of the folder containing the Oracle Application Express static resources used by Oracle REST Data Services, or press Enter if you do not want to specify this location.
3. When prompted select if you want Oracle REST Data Services to generate a self-signed certificate automatically or if you want to provide your own certificate. If you want to use your own certificate, provide the path for the Certificate and DER encoded related private key when prompted.

   If the private key has not already been converted to DER, see section, Converting a Private Key to DER (Linux and Unix) before you enter the values here.

   You are only prompted for these values the first time you launch standalone mode.

   Note:

   Ensure that no other servers are listening on the port you choose. The default port 8080 is commonly used by HTTP or application servers, including the embedded PL/SQL gateway; the default secure port 8443 is commonly used by HTTPS.

To stop the Oracle REST Data Services server in standalone mode, at a command prompt press Ctrl+C.

You can configure a doc root for standalone mode to deploy static resources that are outside the /i folder that is reserved for Application Express static resources.

To do so, specify the --doc-root parameter with the standalone mode command, as in the following example:

java -jar ords.war standalone --doc-root /var/www/html

The preceding example makes any resource located within /var/www/html available under http://server:port/. For example, if the file /var/www/html/hello.txt exists, it will be accessible at http://server:port/hello.txt.

The value specified for --doc-root is stored in ${config.dir}/ords/standalone/standalone.properties in the standalone.doc.root property. If a custom doc root is not specified using --doc-root, then the default doc-root value of ${config.dir}/ords/standalone/doc_root is used. Any file placed within this folder will be available at the root context.

This approach has the following features and considerations:

• HTML resources can be addressed without their file extension. For example, if a file named hello.html exists in the doc root, it can be accessed at the URI http://server:port/hello.

• Attempts to address a HTML resource with its file extension are redirected to the location without an extension. For example, if the URI http://server:port/hello.html is accessed, then the client is redirected to http://server:port/hello.

  The usual practice is to serve HTML resources without their file extensions, so this feature facilitates that practice, while the redirect handles the case where the resource is addressed with its file extension.

• Index pages for folders are supported. If a folder contains a file named index.html or index.htm, then that file is used as the index page for the folder. For example, if /var/www/html contains /abc/xyz/index.html, then accessing http://server:port/abc/xyz/ displays the contents of index.html.

• Addressing a folder without a trailing slash causes a redirect to the URI with a trailing slash. For example, if a client accesses http://server:port/abc/xyz, then the server issues a redirect to http://server:port/abc/xyz/.

• Resources are generated with weak etags based on the modification stamp of the file and with a Cache Control header that causes the resources to be cached for 1 hour.

You can download Oracle WebLogic Server from Oracle Technology Network.

To learn more about installing Oracle WebLogic Server, see Oracle Fusion Middleware Getting Started With Installation for Oracle WebLogic Server and Oracle Fusion Middleware Installation Guide for Oracle WebLogic Server.

You must complete this step before deploying Oracle REST Data Services on WebLogic.

If you are using Oracle Application Express, you must create a web archive to reference the Oracle Application Express, image files. However, if you are not using Oracle Application Express, you may skip the rest of this section about configuring Oracle Application Express images.

Before you begin, you must create a web archive (WAR) file to reference the Oracle Application Express image files. Use the static command to create a web archive file named i.war:

java -jar ords.war static <apex directory>\images

Where:

• <apex directory> is the directory location of Oracle Application Express.

This command runs the static command contained in the ords.war file. It packages the Application Express static images into an archive file named i.war.

The created images WAR does not contain the static resources; instead, it references the location where the static resources are stored. Therefore the static resources must be available at the specified path on the server where the WAR is deployed.

Use the i.war file to deploy to WebLogic in the following steps:

1. Launching the Administration Server Console

2. Installing the Oracle WebLogic Server Deployment

3. Configuring WebLogic to Handle HTTP Basic Challenges Correctly

1. Start an Administration Server.
2. Launch the WebLogic Administration Console by typing the following URL in your web browser:

   http://<host>:<port>/console
   

   Where:

   • <host> is the DNS name or IP address of the Administration Server.

   • <port> is the port on which the Administration Server is listening for requests (port 7001 by default).

3. Enter your WebLogic Administrator username and password.
4. If your domain is in Production mode, click the Lock & Edit button on the left-pane below the submenu Change Center. If your domain is in Development mode, this button does not appear.

By default WebLogic Server attempts to intercept all HTTP Basic Authentication challenges. This default behavior needs to be disabled for Oracle REST Data Services to function correctly. This is achieved by updating the enforce-valid-basic-auth-credentials flag. The WebLogic Server Administration Console does not display the enforce-valid-basic-auth-credentials setting. You can use WebLogic Scripting Tool (WLST) commands to check, and edit the value in a running server. 

The following  WLST commands  display the domain settings:

connect('weblogic','weblogic','t3://localhost:7001')
cd('SecurityConfiguration')
cd('mydomain') 
ls()

If the domain settings displayed, contains the following entry:

-r--   EnforceValidBasicAuthCredentials             true

Then you must set this entry to false.

To set the entry to false, use the WLST commands as follows:

connect('weblogic', 'weblogic', 't3://localhost:7001')
edit()
startEdit()
cd('SecurityConfiguration')
cd('mydomain')  
set('EnforceValidBasicAuthCredentials','false')
save()
activate()
disconnect()
exit()

In the Summary of Deployments, select the Control tab and verify that both the ords and i State are Active and the Health status is OK.

If ords and/or i are not Active, then enable them. In the Deployments table, select the check box next to ords and/or i. Click Start and select Servicing all requests to make them active.

You can install Oracle REST Data Services with GlassFish Server. GlassFish Server is available for download from the Oracle Technology Network.

You must complete this step before deploying Oracle REST Data Services on GlassFish.

If you are using Oracle Application Express, you must create a web archive to reference the Oracle Application Express, image files. However, if you are not using Oracle Application Express, you may skip the rest of this section about configuring Oracle Application Express images.

Before you begin, you must create a web archive (WAR) file to reference the Oracle Application Express image files. Use the static command to create a web archive file named i.war:

java -jar ords.war static <apex directory>\images

Where:

• <apex directory> is the directory location of Oracle Application Express.

The created images WAR does not contain the static resources; instead, it references the location where the static resources are stored. Therefore the static resources must be available at the specified path on the server where the WAR is deployed.

Use the i.war file to deploy to GlassFish in the following steps:

1. Launching the Administration Server Console

2. Installing the GlassFish Server Deployment

1. Launch the Administration Console by typing the following URL in your web browser:

   http://localhost:4848
   

2. If prompted, log in to the Administration Console.

   Tip:

   You are prompted to log in if you chose to require an administration password at the time GlassFish server was installed.

You can download Apache Tomcat from:

You must complete this step before deploying Oracle REST Data Services on Apache Tomcat.

If you are using Oracle Application Express, you must create a web archive to reference the Oracle Application Express, image files. However, if you are not using Oracle Application Express, you may skip the rest of this section about configuring Oracle Application Express images.

To configure Oracle Application Express Images on Apache Tomcat:

• Copy the contents of the <apex directory>/images folder to <Tomcat directory>/webapps/i/.

  Where:

  • <apex directory> is the directory location of the Oracle Application Express distribution.

  • <Tomcat directory> is the folder where Apache Tomcat is installed.

1. Move the ords.war file into the webapps folder where Apache Tomcat is installed.

   Tip:

   Apache Tomcat determines the context root from the file name of a WAR archive. If you need to keep backward compatibility, so that URLs are of the form http://server/apex/... rather than http://server/ords/..., then you must rename ords.war to apex.war before moving it into to the webapps folder.

2. Access Oracle Application Express by typing the following URL in your web browser:

   http://<hostname>:<port>/ords/
   

   Where:

   • <hostname> is the name of the server where Apache Tomcat is running.

   • <port> is the port number configured for Apache Tomcat application server.