- 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.
- 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.
Database Configuration Assistant Support
This release introduces a RESTful interface to the Database Configuration Assistant (DBCA) to create and delete databases. See section 10.4 Configure environment services in the ORDS documentation.
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
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_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 18.104.22.168 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.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 22.214.171.124 and later in this release.
Disabling/enabling PDB Lockdown Profile during install/upgrade
For Oracle database 126.96.36.199 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.2.0
The following changes and enhancements have been made since 19.1.0:
Issues Fixed in 19.2.0
- BUG:29884541 - Force newline characters in
Error-Reason headers to be replaced by space characters to avoid error on WebLogic
- BUG:29942773 - Force use of
APEX_PUBLIC_USER when dispatching APEX Static Resources service
- BUG:24941023 - Handle pound character in URL path values
- BUG:28871609 - Improve Open-API documentation for date time fields
- BUG:29028746 - Dispatch APEX static resources using built in ORDS service
- BUG:29422705 - Enumerate exact set of OWA packages that access is restricted to
- BUG:29536670 - Uptake Oracle JDBC Driver PSE 29010517 to address loss of data in PL/SQL Gateway calls
- BUG:29550323 - The root cause for this issue was addressed by uptaking 19.3.0 Oracle JDBC Drivers, see BUG:29803162
- BUG:29642673 - Fix problem with output being truncated for multi-byte characters in PL/SQL Gateway responses
- BUG:29693752 - Fix problem with detection of SQL Administrator role on 12+ non container database
- BUG:29809280 - Make installer more resilient to error conditions in customer database
- BUG:29843652 - Improve performance of built in Java based REST endpoints
- BUG:29719737 - Fix problem with detection of APEX when APEX is installed in a CDB using Application Containers
- BUG:29711406 - Fix problem with ICAP integration in some environments
- BUG:29803162 - Uptake Oracle JDBC Drivers 19.3.0
- BUG:29617151 - Uptake Eclipse Jetty 9.4.18
- BUG:29778333 - Uptake PDFBox 2.0.15
- BUG:29872040 - Uptake Jackson 2.9.9
- BUG:29615441 - Uptake Guava 27.1
- BUG:29191117 - Uptake Javassist 3.24.1-GA
New Features in 19.2.0
- BUG:29778399 - Provide script to provision a database user to be able to install ORDS database schema
- BUG:29629522 - Propagate authenticated user to database as
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
- 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 188.8.131.52 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
- 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
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.
- 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.