Understanding ORDS Pre-Hook Functions

In Oracle REST Data Services (ORDS), pre-hook functions are utilised to perform preliminary checks before a REST API service processes a request. These checks may include user verification, enforcement of business rules, or restriction of access.
Overview of Operation:
When a client submits a request to the REST API, ORDS first verifies authorisation based on predefined roles and privileges. If authorisation is granted, ORDS invokes the designated pre-hook function. The pre-hook logic determines whether the request proceeds (by returning true) or is blocked (by returning false, resulting in a 403 Forbidden response). Should authorisation fail initially, ORDS will immediately return a 401 Unauthorized status, bypassing the pre-hook entirely.
Setting Up Pre-Hook Functionality:
Oracle provides demonstration code to facilitate implementation of pre-hook functions.
Configuration Steps:
• Open a terminal and navigate to the directory containing pre-hook examples:
cd examples/pre_hook/sql/
• Connect to your database via Oracle SQLcl:
sql system/<your-db-password>
• Execute the installation script, specifying a password for the test user:
@install myTestPassword123
This process establishes:
• A schema defining pre-hook functions,
• A sample user ([e-mail]) with your chosen password,
• An additional schema supporting demonstration REST services.
Example: Restrict All Access
To deny all requests, implement a function as follows:

create or replace function deny_all_hook return boolean as
begin
    return false;
end;
/
grant execute on deny_all_hook to public;

Configure ORDS to utilise this function by updating the settings.xml file:
<entry key="procedure.rest.preHook">pre_hook_defns.deny_all_hook</entry>
After restarting ORDS, all attempts to access the REST API will result in a 403 Forbidden response.
Example: Permit Unrestricted Access
Alternatively, modify the function to allow all requests:

create or replace function deny_all_hook return boolean as
begin
    return true;
end;
/

Requests will be processed regardless of authentication status; unauthenticated users will receive a message such as:

{
    "authenticated_user": "no user authenticated"
}

Use Cases for Pre-Hook Functions
Pre-hook functions are beneficial for implementing scenarios such as:
• Validating user tokens or sessions
• Logging incoming requests
• Restricting access to specific hours
• Enforcing supplementary business logic beyond standard ORDS privileges