Silently Deprecated: When ORDS Quietly Stopped Serving Our Old Oracle APEX URLs
Our documented, tried-and-tested URL pattern stopped working after I upgraded Oracle Rest Data Services (ORDS), and none of the release notes warned me.
When you've been building APEX applications for as long as we have, eventually the way you've always done things becomes outdated. Usually, though, you find out through a deprecation notice or a release note, helping you to plan those changes. That isn’t what happened. This time we found out through a wall of 500 Internal Server Error responses.
This post covers what broke, how we tracked it down, and the fix we're using.
A Little Background On Us
Our engineering team at RADAPEX have been building APEX applications since Oracle released the tool, long before I joined the team. We are APEX specialists. Even my 21 year old colleagues have forgotten more about APEX applications than I will ever know. Not only have we been building APEX apps for a quarter of a century, we still, to this day, support applications that were created long, long ago, and for one client, our documentation records their URLs in this form:
https://<host>/ords/<workspace>/r/<app>For example:
This pattern worked for years. Right up until I touched it in fact…..Before I upgraded anything, we were running APEX 24.2, on an Oracle 19 database and ORDS version 24.4 on a standalone container behind an nginx reverse proxy.
What broke
We upgraded ORDS from 24.4.0.345.1601 to 26.2.2.204.1619. A handful of other dependencies were patched in the same window but, after rolling back and tested separately, ORDS was proven to be the cause. APEX itself stayed at 24.2 throughout.
After the upgrade, every application URL in the documented format returned:
500 Internal Server ErrorNothing else changed: same applications, same APEX version, same database, same proxy. The only variable was ORDS.
Digging in
We went looking for a reason and found it in the APEX documentation, not the ORDS release notes.
The URL pattern we'd documented matches the friendly URL syntax introduced in APEX 20.1 and described in the 21.1 App Builder User's Guide:
The 22.2 version of the same page describes a different structure:
The r segment (the "router shortcut") moved from after the path prefix to before it. When we switched our URL to the newer form, the application loaded immediately:
URL | |
Old (500 on ORDS 26.x) | /ords/apps/r/myapp |
New (works) | /ords/r/apps/myapp |
In our case the path prefix and workspace name are the same (apps), which is the default behaviour. Oracle's docs note that the path prefix defaults to the workspace name when a workspace is created, but it can be customised.
Where Oracle documented the change
This is where it gets interesting. It turns out that the change was announced, just not where you'd look for an ORDS regression.
The APEX 22.1 release notes include a "Changed Behavior" entry titled URL Format Changed for Friendly URL and Static File Support. In short:
Before 22.1, friendly URL and static file handling relied on APEX-based REST Services.
APEX 22.1 desupported APEX-based REST Services.
The ORDS r servlet now handles friendly URLs and static files.
The URL format changed from /path_prefix/r/app_alias/ to /r/path_prefix/app_alias/.
The same release notes cover the desupport itself under APEX-Based REST Services Desupported, and the notice has been carried forward through later release notes.
So in APEX 22.1, Oracle documented that the old format was changing and that the mechanism behind it was desupported. We were on 24.2, well past that point, and our URLs kept working. What we saw is consistent with ORDS continuing to honour the legacy route for several major versions and then no longer doing so in 26.x.
I want to be careful here, because we haven't found anything from Oracle that confirms this. The ORDS 26.1.0 release notes (and all release notes >24.2 and <26.2) list new features and bug fixes, including vector APIs, runtime pool loading, export API changes and OpenTelemetry metrics, plus an upcoming change to supported Tomcat and WebLogic versions. They say nothing about friendly URLs, the r servlet, or the removal of the legacy path. As far as we can tell, the end of support for the old format was never announced in an ORDS release. That's why I'm calling it silently deprecated: the deprecation was announced in the APEX notes in 2022, but the ORDS side never flagged when the legacy handling would stop.
(Our reading of the cause is an inference from the documentation, not an Oracle statement. If someone from the ORDS or APEX team can confirm or correct it, we'd love to hear it.)
Our fix: a redirect at the proxy
Our users have almost certainly bookmarked the old URLs, so we couldn't just change the documentation and move on. Moreover, if we did, we’d end up swamped by support tickets that would embarrassingly be solved asking them to shuffle 2 characters around in their bookmarked URLs. That isn't a good user experience. Luckily, though, you’ll recall that I said our infrastructure was set up with ORDS sitting behind an nginx reverse proxy. We therefore decided that the simplest fix was to redirect the old pattern to the new one at the proxy. All in all, this was a quick fix, once we knew the problem. Finding the problem was anything but quick (isn’t that always the case in this industry).
We tested this against every application and everything resolves correctly. For now the redirect is a stopgap. We'll advise our customers to update their bookmarks and links in due course, then we’ll retire the rule.
If you're about to upgrade ORDS
A short checklist:
Check which URL format your applications and documentation use. If you see /ords/<prefix>/r/..., you're on the legacy form. We didn’t know because it had never been a problem.
Test your application URLs on a non-production ORDS 26.x instance before upgrading. A 500 is a very visible way to find this.
Search bookmarks, internal docs, emails, SSO redirect URIs, monitoring checks and any hard-coded links for the old pattern.
Plan a redirect at your reverse proxy or load balancer for users with saved links.
Wrapping up
None of this is a criticism of the ORDS or APEX teams. Nor is it a criticism of ours. The change in format has been documented since version 22.1. That said, a legacy path that quietly keeps working for years teaches people to rely on it, and the end of that support deserves its own line in a release note.
If you maintain a long-lived APEX estate, check your URLs before your next ORDS upgrade.
For more blog posts from our team, visit https://www.radapex.com/blog
