Accessing CGI Information from ORDS Handlers

Background

OWA_UTIL is a database package that provides access to PL/SQL Common Gateway Interface (CGI) variables. Oracle REST Data Services (ORDS) 2.0 introduced a full OWA environment allowing us to tap into the information provided by OWA_UTIL.

So, why is this useful to me? OWA_UTIL holds a significant amount of information about the environment in which your ORDS PL/SQL handler is being called. This includes information such as the character set, host name, port, web service name and even information about the caller of the service such as the user agent.

In this post I will take you through an example of how to tap into the CGI information available to you in OWA_UTIL. Before we get started, however, you should know that the OWA environment is only available for ORDS POST, PUT and DELETE services. The OWA environment is not set for Collection or Query GET handler types.

What CGI Variables are Available?

By far the quickest (and best) way to see what CGI variables are available to ORDS is to use 'owa_util.print_cgi_env'. This will print out all of the CGI variables in the current session. At this point you may ask how do I see this from my ORDS web service? Well it is easier than you may think.

First of all, let's create a basic ORDS module, resource template and GET handler to use for our CGI tinkering. The slide show below, illustrates my example service:

Note: The GET handler Source Type is PL/SQL. Now that we have a get handler, all we need to do it add a PL/SQL block with a call to  owa_util.print_cgi_env:

All that is left to do is call the web service, I am going to illustrate this using CURL:
curl -X GET -H "Accept: application/json" -H "Cache-Control: no-cache" "https://example.com:443/ords/ordstest/master/owablog"

After running the CURL command, you should see a list of the CGI variables, I have a link below to a file with the full response but wanted to illustrate some some of the more interesting ones:

• accept = application/json
• APEX_LISTENER_VERSION = 3.0.5.124.10.54
• REQUEST_METHOD = GET
• PATH_INFO = /owablog
• SCRIPT_NAME = /ords/ordstest/master
• REMOTE_USER = ORDSTEST
• REQUEST_CHARSET = AL32UTF8
• REQUEST_IANA_CHARSET = UTF-8
• REQUEST_PROTOCOL = https
• REQUEST_SCHEME = https
• SERVER_NAME = example.com
• SERVER_PORT = 443

Having this information available opens up some interesting possibilities:

1. You can develop a generic logging API to log web service calls. A combination of PATH_INFO, SCRIPT_NAME and REQUEST_METHOD can be used to identify the service and log all your web service calls to to a log table.
2.  The caller of the service (in this case our CURL command) indicated they wanted a JSON response. Having access to this HTTP header value is key in us being able to honor this response. Of course, in this case we could have added a parameter to our handler to get this HTTP header value from a bind variable.
3. If you have some code that is ORDS version specific, it may be handy to know the version of ORDS which is running.

full_response_listing_all_cgi_variables.txt
File Size:	1 kb
File Type:	txt

Download File

---

Referencing Individual Values

Now that we know what information we have access to, how do we access it without having to parse the results of 'print_cgi_env'?

The short answer is to use 'owa_util.get_cgi_env'. You simply pass the name of the variable you want and it will return the value. Let's change the Handler for our GET service so that it responds with the URL used to call the web service.

If we run the CURL command again:
curl -X GET -H "Cache-Control: no-cache" "https://example.com:443/ords/ordstest/master/owablog"
We should get the following:
You called me with: https://example.com:443/ords/ordstest/master/owablog

Conclusion

In this post, we have seen why having access to the CGI information for a web service call can be useful and how you can get access to that information from within an ORDS session.