We’re sorry. We could not find a match for your search.

We suggest you try the following to help find what you’re looking for:

  • Check the spelling of your keyword search.
  • Use synonyms for the keyword you typed, for example, try "application" instead of "software."
  • Start a new search.
Cloud Account Sign in to Cloud
Oracle Account

Oracle REST Data Services

Release Notes
Date: April 2019


  • You are supported by Oracle Support under your current Oracle Database Support license for Oracle REST Data Services production releases .
  • Log Oracle REST Data Services bugs and issues using My Oracle Support.

    • For problems specific to SODA for REST, file a service request using "Oracle XML Developers Kit" as the product.
    • For all other problems, use "Oracle REST Data Services" as the product.


  • Documentation for this release is provided on the OTN web site. Click here to view the documentation.
  • Documentation on using SODA for REST is provided on OTN here.

Getting Started

  • A tutorial on getting started with developing RESTful Services is included in the product documentation , in the book titled 'Oracle® REST Data Services Quick Start Guide'.


  • You can discuss issues on the forums.
    • Be sure to use clear subject lines to initiate a thread. Provide a complete and clear description of the issue, including steps to reproduce the issue.
    • Try to avoid using old, unrelated threads for a new issue.

Important Changes to Note

Database Management REST API

This release sees the introduction of the Database Management REST API. Please consult the ORDS documentation library for instructions on how to enable this feature, which is disabled by default.

Install ORDS with non SYS as SYSDBA user

The installer has been enhanced to enable installation of ORDS to a pluggable database, or a non container database without requiring use of the SYS user or a user with the SYSDBA role. Note that installation to a CDB still requires use of the SYS as SYSDBA user. Also note that installation as a non SYS user requires the user to have a number of database privilege grants, please consult the ORDS documentation library for information on how to provision a database user to be able to install ORDS.

Change to scheduled housekeeping job

DBMS_SCHEDULER job CLEAN_OLD_ORDS_SESSIONS has been replaced by ORDS_HOUSEKEEPING_JOB which will perform the same action of deleting expired sessions that are older than one day.

During upgrade to this ORDS release, the CLEAN_OLD_ORDS_SESSIONS job will be replaced by ORDS_HOUSEKEEPING_JOB, if the old job already exists, otherwise the new job will be created when the first schema is enabled via calls to ORDS.ENABLE_SCHEMA or ORDS_ADMIN.ENABLE_SCHEMA PL/SQL methods.

Deprecation of Apache FOP PDF Support

Support for generating PDF responses for PL/SQL Gateway calls will be removed in ORDS 19.2.0. This will impact the features in Oracle Application Express relating to generating PDF documents. Future versions of Oracle Application Express will move to a new mechanism to generate PDF resources.

Deprecation of URI Template Syntax for ORDS Based REST Services

Support for defining ORDS based REST Services using the original URI Template syntax (as used in APEX based REST Services) will be removed in ORDS 19.4.0. Customers are strongly encouraged to modify Resource Module definitions to use the more robust and expressive Route Patterns Syntax.

Deprecation of Regular Expression based URL Mappings

Support for defining URL mappings using the java -jar ords.war map-url --type regex is deprecated. It is recommended that customers use --type base-path or --type base-url instead. Support for --type regex will be removed in ORDS 19.4.0.

Supported WebLogic Version

Oracle REST Data Services is compatible with Oracle WebLogic and later. It is not compatible with older versions of Oracle WebLogic.

Improvements to PL/SQL Gateway to aid transition from mod_plsql

In ORDS 18.2.0 support was introduced for authenticating database users via HTTP Basic authentication (see below). In ORDS 18.3.0 the following changes have been made aimed at faciliating customers migrating from Oracle mod_plsql:

Custom Authentication Stored Function Support

With mod_plsql customers enabled custom authentication by implementing a stored function named: OWA_CUSTOM.AUTHORIZE. Oracle REST Data Services provides equivalent functionality via the security.requestAuthenticationFunction stored function. This setting names a stored function that takes zero arguments and returns a boolean indicating if authentication was succesful or not. The function should use the Oracle Web Agent (OWA) PL/SQL APIs to examine any or all of the following package level variables: owa.user_id, owa.password, owa.ip_address and owa.hostname and/or the OWA APIs to examine the request's headers and parameters.

Note that this facility is provided to assist customers migrating from existing mod_plsql installations. Its use is not recommended outside of these scenarios, as it uses HTTP Basic authentication only.

Per Request Validation

One difference in behaviour between Oracle REST Data Services and mod_plsql is that out of the box ORDS caches the result of validating a procedure name. The intent is that the set of whitelisted procedure names is fixed, and thus validation outcomes can be cached. However mod_plsql does not behave this way, the request validation function is invoked on every request. In addition the request validation function is executed after the OWA (Oracle Web Agent) environment has been initialized for the request, so the validation function can examine the headers and parameters of the request, and thus can make decisions about whether to authorize the request based on the contents of the request in addition to the name of the procedure being invoked.

Some mod_plsql customers have come to rely on this behaviour to perform application specific validation, user authentication and authorization, thus to facilitate those customers, ORDS 18.3.0 provides the capability to replicate this behaviour of mod_plsql. This done by setting the configuration property named: security.maxEntries to zero. This can be done in defaults.xml (if it should apply across all pools) or in a specific pools configuration file. Setting this value to zero disables caching of procedure validations, leading to behaviour equivalent to mod_plsql.

HTTP Basic dynamic authentication for PL/SQL Gateway requests

To facilitate customers migrating from Oracle mod_plsql to Oracle REST Data Services, this release introduces support for authentication of database users using HTTP Basic Authentication. This functionality is equivalent to the Basic authentication mode in mod_plsql where the database user name and password are omitted from the mod_plsql DAD.

For performance and security reasons we strongly advise customers not to use database authentication in general. The only way to validate a database password is by creating a connection to the database, which is very expensive. Database passwords are often weak and poorly chosen on the assumption that they are not accessible from the web. The HTTP Basic Authentication scheme lacks a mechanism for terminating (logging out) a user session. The only way to end the session is to close the Browser.

The only scenario where using database authentication is acceptable is for migrating existing applications from mod_plsql that are reliant on database authentication, and the database is appropriately configured with a strong password strength and expiration policy.

RESTful Services Pre-Hook Function

ORDS 18.3.0 introduces the ability for a stored function to be invoked prior to the dispatching of an ORDS based RESTful Service. This facility enables customers to perform additional request validation and authorization and/or configure the database session as required. In addition this facility provides a means for the pre-hook to assert the identity and roles of the user making the request, thus facilitating integration with custom authentication mechanisms.

Changes to Installation in CDB$ROOT

As of release 18.2.0, ORDS no longer installs its ORDS_METADATA schema into the CDB$ROOT container. Now only the ORDS_PUBLIC_USER common user is installed in the CDB$ROOT (and ALL PDBs connected to the CDB). The ORDS_METADATA schema is installed in each PDB connected to the CDB. This aids future upgrades of ORDS, minimizing downtime as the CDB and PDBs will no longer need to be all taken offline at the same time for an ORDS upgrade.

The installation changes are supported for Oracle database and later in this release.

Disabling/enabling PDB Lockdown Profile during install/upgrade

For Oracle database or later, the installer will check if the PDB initialization parameter PDB_LOCKDOWN contains a PDB lockdown profile. If a PDB lockdown profile exists, then it will disable the PDB lockdown profile during ORDS install or upgrade, and will enable it when the install or upgrade completes.

If you do not want the ORDS installer disabling the PDB lockdown profile during ORDS install or upgrade, then you can set the pdb.disable.lockdown property to false in the ORDS parameter file:


Supported Java Version

Oracle REST Data Services requires Java 8 or later. Java 7 is no longer supported. Please consult the documentation for the minimum supported Application Server versions for ORDS.

Changes in 19.1.0

The following changes and enhancements have been made since 18.4.0:

Issues Fixed in 19.1.0

  • BUG:29544918 - Fix problem with Standalone Mode producing WARN level messages during startup
  • BUG:29532796 - Fix problem with WebLogic raising 'Cannot contain CRLF Charcters' (sic) error
  • BUG:29524572 - Remove Apache Avalon third party dependency
  • BUG:29193867 - Fix problem with invocation of ORDS_ADMIN.DEFINE_SERVICE and ORDS_ADMIN.DEFINE_HANDLER APIs
  • BUG:29290410 - Add DOC_SIZE, DAD_CHARSET and CONTENT_TYPE to file upload in document table
  • BUG:29303722 - Improve how string arrays are transferred from ORDS to the database on 12C and later
  • BUG:29210421 - ORDS corrupting timestamps of ords.war contents when running configdir command
  • BUG:29197220 - Dispatch PL/SQL Gateway calls via ORDS_PUBLIC_USER to minimize number of pools required
  • BUG:29191117 - Uptake Javassist 3.24.1-GA
  • BUG:29191097 - Uptake Eclipse Jetty 9.4.14
  • BUG:29191084 - Uptake Google Guava 27.0.1
  • BUG:29190987 - Uptake Jackson 2.9.8
  • BUG:29190934 - Uptake Apache Commons File Upload 1.4
  • BUG:29190890 - Uptake Apache PDFBox 2.0.13
  • BUG:29128000 - Connect to database using Wallet Zip archive as found Oracle Database Cloud ATP/ADW environments
  • BUG:28570782 - Improve integration with McAfee ICAP Server
  • BUG:27639517 - Provide mechanism to enable Plugin servlets function as an administrative database user

New Features in 19.1.0

  • ENH:29303772 - Enable ORDS to install in a PDB without requiring SYS user or SYSDBA role

Changes in 18.4.0

The following changes and enhancements have been made since 18.3.0:

Issues Fixed in 18.4.0

  • BUG:29053557 - Determine administrative database users based on granted database role
  • BUG:29049176 - Show 403 Forbidden status when REST Service fails due to database user lacking privilege to access objects referenced in the SQL statement
  • BUG:28520359 - Show Oracle Logo in UI
  • BUG:29011184 - Suppress unsupported and undocumented X-DB-Content-Length response header produced by OWA
  • BUG:28877175 - Fix resolution of url-mapping.xml based mapping that uses --workspace-id
  • BUG:28997641 - Gracefully cope with database password rotation
  • BUG:28964132 - ORDS installer won't accept passwords more than 28 bytes long
  • BUG:28808094 - Uptake Apache Commons Logging 1.2
  • BUG:28787846 - Uptake Apache PDFBox 2.0.12
  • BUG:28719460 - Uptake Javassist 3.23.1-GA
  • BUG:28719440 - Uptake Jetty 9.4.12
  • BUG:28719424 - Uptake Jackson 2.9.7
  • BUG:28561298 - Address problem with upgrading from ORDS 17.4.1
  • BUG:28518849 - Fix problem with OAuth token lifetimes not being calculated correctly
  • BUG:28466581 - Fix 500 Error status on open-api-catalog resources
  • BUG:27992525 - Fix access to metadata-catalog when no authorization required
  • BUG:27933884 - Fix parsing of Resource Handler content to recognize parameters more precisely
  • BUG:27808357 - Enhance performance of AutoREST tables/views

New Features in 18.4.0

  • ENH:23666046 - Make security.requestValidationFunction setting configurable per database pool
  • ENH:28028432 - Echo p_comments value into generated Swagger documentation

Changes in 18.3.0

The following changes and enhancements have been made since 18.2.0:

Issues Fixed in 18.3.0

  • BUG:28700464 - Prevent caching of connections created via database authentication, leading to issues when database password changed
  • BUG:28672484 - Fix problem that prevented PL/SQL Gateway file uploads working in non APEX environments
  • BUG:28567990 - Fix regression that prevented dispatching of APEX based REST Services in CDB
  • BUG:28518849 - Fix regression that caused OAuth token lifetimes to 1000 times what they should be
  • BUG:23640562 - Provide means for authorized administrative database users to define ORDS REST Services in any schema
  • BUG:28581365 - Fix 500 error problem that may occur when using database authentication
  • BUG:28543131 - Enable a PL/SQL function to be invoked prior to dispatching ORDS RESTful Services
  • BUG:26712420 - Fix issue with ORDS installer failing when using RAC
  • BUG:28529274 - Fix problem during install when database auditing is enabled
  • BUG:28528895 - Fix problem during install with closed PDBs using PDB lockdown
  • BUG:28502103 - Deprecate legacy X-APEX-STATUS-CODE and similar headers, replace with X-ORDS-STATUS-CODE etc.
  • BUG:28500353 - Uptake Jetty 9.4.11
  • BUG:28500351 - Uptake Guava 26.0
  • BUG:28500334 - Uptake Apache FOP 2.3
  • BUG:28499759 - Fix problem with missing third party library: Javassist
  • BUG:28485975 - Uptake Oracle JDBC drivers
  • BUG:28481972 - Fix problem with the casing of user chosen password
  • BUG:28460781 - Fix problem with URL encoding of pound character in hyperlink values
  • BUG:28445474 - Fix problem causing a query that uses manual pagination still being wrapped in an auto pagination clause
  • BUG:28432949 - Enable self links in ORDS REST Services to have a trailing slash
  • BUG:28407676 - Fix problem with ORDS schema alias 'hiding' APEX schema alias and preventing APEX based REST services from dispatching, causing plugin and application images to 404
  • BUG:28394698 - Fix problem with performance of logging in certain cases when debug.printDebugToScreen enabled
  • BUG:28394684 - Fix problem with masking of data in log files causing performance issues
  • BUG:28352768 - Implement HEAD support for APEX based REST Services

New Features in 18.3.0

  • ENH:28603664 - PL/SQL Gateway support for custom authentication
  • ENH:28603635 - Provide means to disable caching of PL/SQL Gateway procedure validation
  • ENH:28304149 - Improve PL/SQL Resource Handler usability

Changes in 18.2.0

The following changes and enhancements have been made since 18.1.1:

Issues Fixed in 18.2.0

  • BUG:28225327 - Update the examples in examples/soda/getting-started/ for the SODA feature
  • BUG:28207743 - Fix resource leaks during AutoREST procedure invocation
  • BUG:28094268 - Fix problem with serving of refreshed APEX static resources on Firefox & Edge
  • BUG:28071398 - Address issue in ICAP functionality causing interoperability problem with McAfee virus scanner
  • BUG:28207044 - Remove the previously deprecated ords-scripts command
  • BUG:27916398 - Fix regression preventing dispatching of ORDS REST Services in APEX workspace where schema name not same as workspace name
  • BUG:28000102 - Gracefully shutdown Standalone Mode, by waiting a short period to complete in flight requests when shutting down
  • BUG:27992366 - Fix regression causing unintended Basic Authentication browser prompt during OAuth Token approval flow
  • BUG:28000102 - Gracefully shutdown Standalone Mode, by waiting a short period to complete in flight requests when shutting down
  • BUG:27994227 - Uptake version 9.4.10 of third party Jetty Library
  • BUG:27994221 - Uptake version 2.9.5 of third party Jackson library
  • BUG:27916570 - Handle migration of APEX based REST services with null URI prefix
  • BUG:24941023 - Change what kind of URL paths are rejected by ORDS, only path traversal attacks are rejected now
  • BUG:28043792 - Support RAW data type for REST Enabled SQL
  • BUG:28086691 - Fix regression that prevents PL/SQL Gateway file uploads working (with NoClassDefFoundError)
  • BUG:27882996 - Fix regression that prevented db.password values prefixed with ! being encrypted
  • BUG:28072133 - Fix issue with OAuth client icons not displaying in approval prompt
  • BUG:27987547 - Fix premature removal of deprecated db.serviceNameSuffix related functionality
  • BUG:28130669 - Ensure ORDS_METADATA schema password matches Oracle Database 18.1 complexity rules
  • BUG:28130678 - Disable/Enable PDB lockdown profile during install
  • BUG:28130669 - ORA-28003 Error during install on Oracle Database 18.1
  • BUG:27832443 - Reduce size of Error Page by eliminating unused CSS

New Features in 18.2.0

  • ENH:28180268 - Require Migration of ORDS_METADATA schema in CDB to PDB
  • ENH:28149866 - Enable APEX workspace users to authenticate against ORDS based REST services
  • ENH:28069808 - Detect when pool is pointing at a CDB service and auto enable URL mapping to each PDB connected to CDB

Changes in 18.1.1

The following changes and enhancements have been made since 18.1.0:

Issues Fixed in 18.1.1

  • BUG:27165873 - Fix issue with ORDS.DELETE_CLIENT failing
  • BUG:27540028 - Migrate CDB install to PDB install
  • BUG:27505895 - Multithreading issue when dispatching resource modules under load
  • BUG:27456593 - Issue with first part token session not expiring correctly
  • BUG:27391040 - APEX OAuth Clients are forced to Token Response type when edited and saved
  • BUG:26881221 - Fix regression preventing authentication of Tomcat based users

New Features in 18.1.1

  • ENH:27741103 - Support HTTP Basic dynamic authentication for PL/SQL Gateway calls

Changes in 18.1.0

The following changes and enhancements have been made since 17.4.1:

Issues Fixed in 18.1.0

  • BUG:27375052 - Eliminate need for --add-modules javax.xml.bind when running ORDS on JDK 9
  • BUG:27374997 - Fix regression causing ORDS not to function on WebLogic 12C out of the box

New Features in 18.1.0


Known Issues


  • None

JDK Support

  • ORDS will run and is supported on JDK 9 however the only supported way to use ORDS on JDK 9 is by running it in standalone mode, as currently neither Oracle WebLogic or Glassfish (PDF) are certified for use with JDK 9, and ORDS has not yet been certified on Apache Tomcat on JDK 9.
  • From ORDS 18.1.0 and later you can launch ORDS on JDK 9 by just typing:

    java -jar ords.war <command-name>

    • The requirement in 17.4 to use the --add-modules java.xml.bind command line argument has been eliminated

JDBC Array values

ORDS passes array values to the Oracle Database in a number of cases, for example arrays are used to pass the request headers and form fields during PL/SQL Gateway calls. Oracle JDBC Driver 18.3 and later supports an improved mechanism for passing array values, however this feature is only supported on Oracle Database 12c and later. Thus ORDS uses existing deprecated and less efficient APIs for passing array values when connecting to 11G databases, and the improved mechanism when connected to 12c and later. Customers experiencing problems with passing large array sets (for example OutOfMemory exceptions) are encouraged to upgrade from 11G to a newer database version to mitigate these issues.

Autogenerated REST Endpoints

  • AutoRest resources support the OAuth 2.0 Client Credentials flow only.

RESTful Services

  • Application Express workspaces do not support first party authentication, and therefore do not support the /sign-in/ interactive sign in form. Accessing /sign-in/ in APEX workspaces will produce a 404 status.

Support For mod_plsql logmeoff

  • The mod_plsql logmeoff mechanism is not supported reliably by modern browsers and it is not provided by ORDS. The only way to end a HTTP Basic Authentication session is to close the Browser.

Starting Standalone Mode when connected to CDB

The typical manner to start ORDS in standalone mode, once ORDS has been configured is:

java -jar ords.war

ORDS will detect that it is fully configured and proceed to launching standalone mode. Since 18.2 the ORDS_METADATA schema is not installed in the CDB, which means that when the default pool is connected to a CDB there is no way for ORDS to automatically verify the version of the ORDS schema installed in the database, thus ORDS prompts for the SYS AS SYSDBA password so it can connect to each PDB and verify the ORDS version installed in each PDB. This means that when connected to a CDB the above command is not sufficient to start standalone mode automatically. To work around this issue, use the following command to start ORDS (only after the ORDS instance has been configured) in standalone mode automatically:

java -jar ords.war standalone

Support for apex.docTable

  • apex.docTable (now depreciated) and owa.docTable should not be used for APEX 4.x and above as APEX provides its own document table.