Oracle REST Data Services 24.1.0

Release Notes

Date: April 2024

Enhancements

  • Interactive Installer now supports Bequeath connections
  • Interactive Installer now displays entries from TNSNAMES
  • Metadata Caching enabled by default with a default timeout of 1 second
    • 3x increase in response times AUTOREST enabled JSON-Relational Duality Views AUTOREST enabled TABLEs
  • REST handlers can use implicit bind :body_json to access the body content in a JSON String
  • REST handler supports SELECT where WITH clause contains PL/SQL procedure or function
  • DB-API support for DBMS_SCHEDULER
  • DB-API new API to create PDBs from PDB$SEED or XML metadata file, or hot clone from another PDB or snapshot, implemented via a DBMS_SCHEDULER job for fast, asynchronous responses
  • Stanadalone ORDS Access Log format has been updated to include enhanced details
    • Pre 24.1
      • "%h %l %u %t "%r" %>s %b"
                   e.g. 127.0.0.1 - frank [10/Oct/2000:13:55:36 -0700] "GET /ords HTTP/1.1" 302
    • 24.1 and higher
      • "%{client}a %u %t "%r" %s %{CLF}O "%{Referer}i" "%{User-Agent}i" %{ms}T %{Host}i" e.g. 192.168.122.1 - [27/Mar/2023:23:00:07 +0000] "GET /ords/ HTTP/1.1" 302 - "-" "Mozilla/5.0 (X11; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/111.0" 132 192.168.122.149:8080

SQL Developer Web

  • Execute Statement button now offers option to disable paging of query results
  • SQL History is now stored in login user schema (DBTOOLS$EXECUTION_HISTORY), making SQL History available to the user from any device. Users lacking privileges or quota will continue to have SQL History stored in browser
  • LaunchPad (home screen) redesigned for improved navigation and user experience, including new features to 'pin' favorite features to the page as well as seeing recently visited pages
  • Data Studio (Autonomous Databases only):
    • When loading data from with the Data Load dashboard, users can now click the "Create Live Feed Button" to view real time status and metrics of a jobs status
    • Supports data loading of geoJSON files
    • ADMIN can now CREATE tables in another users schema
    • AWS Glue support (introductory support for Analyze, Ingest, and Lineage)
    • Enable OCI Resource Principal
    • OCI Data Catalog Registration and Synchronization
    • Catalog, new interface for creating database links
    • Support data loading from heterogenous DB Links

Bug Fixes

  • 36353826 URISyntaxExceptions will now be returned as 400 Bad Requests vs 500 with Severe messages in the Log
  • 30661150 “org.eclipse.jetty.io.EofException" or "java.io.IOException: Connection reset by peer" exceptions no longer logged as 500/Severe
  • 36329458 5xx response when GET ends with a trailing "?", e.g. limit=10000?
  • 35942592 cache.metadata.graphql.expireAfterWrite and cache.metadata.graphql.expireAfterAccess now recognized by ords config
  • 36253527 ORDS fails to start on Solaris
  • 36237250 basic authentication fails with lowercase usernames
  • 36086429 ORDS extract scripts CLI on Windows fails
  • 36019047 Interactive Installer default to forward slashes on Windows OS systems
  • 35998046 ORDS CONFIG INFO JDBC.INITIALLIMIT command displays wrong value
  • 35952549 Weblogic Sever 500/Severe when a client sends Host with trailing whitepace in hostname
  • 35645537 mixed case (poolNameOne) and upper case (POOLNAMEONE) pool names invalid (404s)
  • 35622566 ORA-01400 POST to INSERT table PK "Timestamp" with default value of SYSTIMESTAMP
  • 35605875 Error screen truncates long messages
  • 35369846 Wrong output parameter enabled procedure with boolean inputs (False vs True)
  • 35062974 Request TIMEOUTs would incorrectly return a 200 HTTP Status Code
  • 34988454 NPE starting ORDS with DynaTrace Oracle APM Agent on same machine
  • 34850573 DispatcherNotFoundException exception when using both pathnames and hostnames
  • 34739274 Default input parameters Enabled PL/SQL ignored, and instead returned null values
  • 30321479 DBAPI tablespaces endpoint would return information on files vs the tablespace
  • 29925004 DBAPI FOREIGN_KEYS only provide information on the first column defined in the constraint

SQL Developer Web

  • 36302941 blank panel when switching Explain Plan to advanced view
  • 36230295 TypeError: cannot read properties when load data from SQL History
  • 36166340 Code selection not working when syntax errors in SQL Worksheet
  • 36165307 No Data to Display error when exporting REST Module to PL/SQL
  • 36077133 Data Pump import failing when using export from SQL Developer desktop
  • 36075770 After creating a REST Privilege, unable to select/unselect Roles from Roles tab
  • 36051433 Creating APEX workspace fails due to the APEX_ADMINISTRATOR_ROLE not being set
  • 36043494 View Scheduler Job Details fails in grid view
  • 36015065 Data Pump "Back" button disabled between steps 1 and 2
  • 35993954 In-context "Help" drawers were cropping help and user guide documents
  • 35993541 Inability to scroll up/down when in the in-context help drawer panels
  • 35895593 ORDS borrowing a connection from its connection pool to serve static content
  • 35519517 Create APEX Workspace UX issues & improvements
  • 34277969 SQL history (found in the SQL Worksheet) will now recognize and record SQL queries sharing the same content, but with varied padding as distinct. (E.g. Select * From DUAL; vs. Select * From DUAL;)
  • 34215246 Sign out now redirects back to login page for the same database/pool of previous session
  • 34070024 SQL worksheet executes wrong statement due to syntax errors found in editor
  • 31572075 "ORA-01756: quoted string not properly terminated." for explain plan/autotrace

GraphQL

  • 36165748 Graphiql card displays when feature has not been enabled
  • 36079558 Inability to authenticate to privilege-protected endpoints

Supported Java Version

Oracle REST Data Services requires Java 11 or 17. The supported Java Runtime Environments are:
  • Oracle Java 11
  • Oracle Java 17
  • Oracle GraalVM Enterprise Edition for Java 11
  • Oracle GraalVM Enterprise Edition for Java 17

Please consult the documentation for the minimum supported Application Server versions for ORDS.

Support

  • 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.
Note - Autonomous Database Shared Subscribers

If you are running a customer-managed ORDS for your Autonomous Transaction Processing, Autonomous Data Warehouse, or Autonomous JSON Database, you must upgrade your customer-managed ORDS to the version used in your Autonomous Database Shared environment. Failure to do so could lead to service disruptions.

To determine the version of ORDS in your Autonomous Database Shared database run this query:

select ords.installed_version from dual;

Documentation

General
  • Documentation for this release is provided on the oracle.com web site. Click here to view the documentation and related information.
  • Documentation on using SODA for REST is provided on the oracle.com web site. Click here, navigate to the documentation section and access the book titled 'SODA for REST'.
Getting Started
  • A tutorial on getting started with developing RESTful Services is included in the ORDS product documentation, in the book titled 'Oracle REST Data Services Quick Start Guide'.

Known Issues

Oracle Database may report 'ORA-01031: insufficient privileges' for queries that involve CURSOR expressions

In a number of cases, ORDS executes queries which include a CURSOR expression. An issue has been found executing these queries for some schemas in Oracle 18c and Oracle 19c databases. Depending on the roles and privileges involved, the issue does not occur for all schemas, which can give the impression that the issue is intermittent. Refer to RDBMS bug 29049673 for more information. The issue is manifest as follows in the exception returned: 

ORA-00604: error occurred at recursive SQL level 1

ORA-01031: insufficient privileges

This is a problem with view-merging of nested cursors introduced in Oracle 18.1 database. Please use the following as a workaround: 

alter system set "_fix_control"='20648883:OFF';
Oracle Database DATE and TIMESTAMP values

ORDS interprets Oracle Database DATE and TIMESTAMP values (which do not possess a time zone) into the time zone of ORDS. These values are then represented in the RFC3339 UTC format.

In a future release Oracle Database DATE and TIMESTAMP values will not by default be interpreted into any time zone. These values will be represented in the ISO 8601 "yyyy-mm-ddThh:mm:ss[.sss]" format. Oracle Database TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE values will remain represented in the RFC3339 UTC format.

SQL Developer Web
  • DATE, TIMESTAMP, TIMESTAMP WITH TIMEZONE values downloaded from the Worksheet Query Result in the JSON format are not presented in the Internet Datetime format.
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.

Feedback

  • At Oracle REST Data Services on oracle.com you will find links to forums and social media channels where you can discuss topics with the ORDS community around the world and leave feedback for the development team.
    • In 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 Concepts to Keep In Mind

Revised Command Line Interface and Configuration Directory Structure

Command Line Interface

The java commands serviced from the WAR file are no longer supported. Attempting to run the following: 

java -jar ords.war standalone
Will result in an error message, referring you to the docs. Instead you would run: 
ords --config /path/to/config serve
Installation & Configuration

The ORDS program or script in the bin directory can be used to perform installs, changes to your configuration, changing the database passwords for your connection pools, and for creating ORDS users. To see a list of commands: 

ords --help
Configuration Files Directory Layout

If upgrading from a previous version of ORDS, your existing configuration directory for ORDS and the files contained therein will be migrated to a new layout for versions 22.1 and higher.

You may migrate your settings using the ORDS migrate command, or you may perform a 22.1 install which will prompt ORDS to migrate your existing ORDS configuration to the new mapping for you.

ORDS standalone and default pool configuration settings are in a settings.xml file in a global subdirectory.

Connection pools are in a databases subdirectory. The intital database pool is named 'default' and has a '/' mapping pattern.

Subsequent pools will created such that the name of the pool also defines the mapping pattern.

SQL Developer Web

SQL Developer Web (SDW) is an ORDS hosted web application giving Oracle Database users the SQL Developer desktop experience in their browser.

SQL Developer Web provides a development interface for building and maintaining your ORDS based REST APIs, AUTOREST Enabled database objects, OAuth3 Clients, ORDS Privileges and Roles, as well as a SODA for REST graphical interface. For the best possible experience developer REST APIs for ORDS, we recommend you use SQL Developer Web.

For consistent representation of date values in SQL Developer Web, ORDS should be run in the UTC timezone. This is set automatically when using the ords command line interface. When deploying ORDS to Apache Tomcat or WebLogic Server the user.timezone may have to be set explicitly before starting the container. 

-Duser.timezone=UTC
SQL Developer Web requires the Database API be enabled.

SQL Developer Web's DBMS_SCHEDULER interface requires database version 12.2 or higher.

Upgrading ORDS in the database

If you have previously executed script, ords_installer_privileges.sql, to grant your administrator user privileges to perform the install or upgrade, then you must execute the script again on that same user that you provided because additional grants have been added to this script. Note: This script does not apply to the SYS user account.

 

Earlier Release Versions

For information on Issues Fixed and New Features introduced for earlier versions please refer to the release notes for those versions.