Understanding the Parameter
Per the documentation, the parameter ‘procedure.rest.preHook’ : “Specifies the function to be invoked prior to dispatching each Oracle REST Data Services based REST Service. The function can perform configuration of the database session, perform additional validation or authorization of the request. If the function returns true, then processing of the request continues. If the function returns false, then processing of the request is aborted and an HTTP 403 Forbidden status is returned.”
Note: The above entry assumes I have a package called rest_utl with a function called pre_hook, which I created in the schema xxords. Here is the package specification for the above example:
The procedure needs to be executable from all schemas that your ORDS services are run from. For example, if you create a Prehook function called REST_UTL_PK.PRE_HOOK in the schema XXORDS, and you are running ORDS services from schemas XXORDS and XXREST, then you must grant execute on XXORDS.REST_UTL_PK.PRE_HOOK to the schema XXREST. If you do not, you will get the following error when running services from XXREST:
Use Case 1 – Table Logging Calls to ORDS Services
The second reason is to track, and trouble shoot errors that occur during web service execution. Obviously, the Prehook function won’t help us with logging errors raised by our web services because at the time it is called, the service has not yet run. It can, however, be used to perform all of our usage logging.
In some cases, we could already do this, by adding the log table insert to our handler logic. This did not, however, work for GET services where our handler was a SQL statement.
Let’s look at how we could go about adding table usage logging for all our ORDS services using the Prehook function.
You may notice in the above example that I am tracking a custom HTTP Header ‘X_USER_NAME’. This is to illustrate that you may want to introduce custom http headers so that you can track additional attributes about the client.
Use Case 2 – Setting Session Context
Before now, we could do this for POST services by including a call to fnd_global.apps_initialize at the start of the handler logic. This was not possible, however, for a GET based on a SELECT statement. This meant we had to build GET services using a PL/SQL block and emit the JSON manually using APEX_JSON.
The Prehook function allows us to call fnd_global.apps_initialize at the start of the session and have that context applied when the web service is called. This is much cleaner.
Use Case 3 – Custom Authorization
I still recommend you use ORDS standard OAUTH token security as your primary method of authorization. If, however, the client cannot support OAUTH, or you need to supplement standard OAUTH with some additional checks, the Prehook function is a great option.
There is an entire section of the ORDS documentation dedicated to this feature which includes examples.
P.S. It will be interesting to see if and how the ORDS development team plans to expose parameters like these to multi-tenant PaaS offerings such as Exadata Express. This may prove a challenge given the parameter is currently set in the parameter file on the server.