ORDS HTTP Headers and Variables Revisited for ORDS3

Background

Back in 2014, I wrote a Blog describing how you can access HTTP header variables and bind variables from ORDS 2.X web services HTTP & HTTP HEADERS OVERVIEW

I thought it would be a good idea to update this for ORDS 3.X as things have changed quite a bit since then.

DEFINITION
HTTP header fields are components of the header section of the request and response messages in the Hypertext Transfer Protocol (HTTP). They define the operating parameters of an HTTP transaction.

REST SERVICE INVOCATION FLOW
This diagram illustrates (at a high level) the flow of a REST http request from the client to web server on to ORDS and then back to the client.

• The client makes an HTTP request, which is directed, to the application server.
• The application server (and ORDS) routes the request to a specific ORDS REST handler, which is stored in the database.
• The handler executes it's PL/SQL code and passes the response back to the Web Server, which in turn passes it back to the client, completing the loop.

ANATOMY OF A HTTP REQUEST

How is a http request constructed?

• HTTP Method
  • In REST, the method indicates what action needs to be performed on the resource. Most commonly this is GET, POST, PUT, DELETE and PATCH.
• Path to Resource
  • This is used to direct the web server to a specific resource / web service.
• Request Headers
  • ​Host: Is the host name of the server where the Web Service is hosted.
  • Authorization: This could be Basic, Bearer, Digest etc.
  • Content Type: Format of payload.
  • Cache-Control: Signifies that the web server should not cache the request.
  • XX-CLIENT-SYSTEM: A custom header to identify the client application.
  • There could be many additional headers
• Request Body
  • This is the payload passed from the client to your web service.

ORDS Variables

COMMON HTTP HEADERS
There are a number of http headers that are commonly used in the http protocol; these are all accessible from ORDS (assuming that the client application provides them). You don’t need to do anything special to reference these headers except add them to the Parameters section of your REST service (see below for details). A list of the most common HTTP headers is available here: List of HTTP header fields, See Section ‘Request fields’.

ORDS SPECIFIC VARIABLES
There are a number of variables (HTTP Headers and Bind Variables) that are ORDS specific. These fall into the categories of inbound (passed into the handler code block by ORDS) and outbound (populated by your PL/SQL code and passed back to the caller by ORDS).
​
​Input Variables
In ORDS 2.X, ORDS provided a number of X-APEX... headers (X-APEX-BASE, X-APEX-PATH, X-APEX-CHARSET, X-APEX-METHOD and X-APEX-PREFERRED-CONTENT-TYPE). You can refer to my 2014 post for details of these. In ORDS 3.X, most of these are no longer available. Fret not, as this information is still there, you just need to use other methods e.g. OWA_UTIL to access it.

In the spirit of not repeating myself, refer to my earlier post on OWA_UTIL for details of how to access the CGI information for a web service call (Accessing CGI Information from ORDS Handlers). Suffice it to say, all of the information that was available to you with X-APEX variables is still accessible in ORDS 3.X.

Output Variables
​Not much changed on the outbound side, there are three key variables you need to be aware of:

Name	Source Type	Data Type	Description
X-APEX-STATUS-CODE	HTTP HEADER	INTEGER	Used to return the http status of your service call to the client/calling application:,e.g. 200 (OK), 201 (Created) etc.
Any Name You Like	Response	String	This provides a bind variable to the Response Message. This is an alternative to using htp.p to output your response.
X-APEX-FORWARD	HTTP HEADER	String	This response header allows you to tell ORDS to call the service identified in this variable and return the result of this service in the response.,e.g. A client calls your service to POST/Create a record, the POST service creates the record and populates this variable with the URL of the newly created record. ORDS will then call the GET REST service for the new resource and respond to the initial POST request with the content returned from the GET service.

CUSTOM VARIABLES
You are not limited to what ORDS provides (or the HTTP Header Field Standards). You can access custom inbound HTTP headers and also populate your own custom response headers.

Accessing Custom Inbound Headers
Custom headers can be used by client applications to send additional information to your service. For example, let’s say you want all of your clients to pass a string that contains the name of the client system. One-way to do this is to have the client pass a custom http header e.g. XX-CLIENT-SYSTEM

Sample HTTP POST request with Custom header XX-CLIENT-SYSTEM:

In order to access this new header from within your ORDS PL/SQL handler code, you can either use either OWA_UTIL or add a parameter:

Using OWA_UTIL:
  l_client_system := owa_util.get_cgi_env('XX-CLIENT-SYSTEM');

Adding a Parameter:

   l_client_system := :xxClientSystem;
​
In my opinion, adding a parameter is the best way to go as this makes it more obvious to people looking at the code in the future that this parameter is there (and it important to the service). BTW, I am using a convention of prefixing my custom headers with 'XX-' this is to avoid clashing with any future ORDS headers or other industry recognized header names.

​Setting Response HTTP Headers
Looking back at the Parameters in the screen shot above we can see that (other than X-APEX-STATUS-CODE) there is a custom response header called XX-RETURN-MSG. We can set the value of the related bind variable 'xxReturnMsg' in our code and the value will appear in the HTTP header of the response which the client system will be able to read. e.g.
  :xxReturnMsg := 'Error in provided data';

Putting it All Together

Let's look at a complete example that incorporates all of the above. In this example, I have a module called 'master' with a single template called 'ordsvars' which has just one POST handler.

Service Module, Template & Handler

The handler for the template has 4 parameters:

• XX-CLIENT-SYSTEM (Bind Variable xxClientSystem)
  • Inbound custom HTTP header variable
• X-APEX-STATUS-CODE (Bind Variable xxhttpStatus)
  • This is a standard ORDS response header that sets the HTTP Status Code
  • Set the value of xxhttpStatus to an appropriate response 200, 401 etc.
• DATA (Bind Variable xxResponse)
  • Outbound variable that will contain the response body
• XX-RETURN-MSG (Bind Variable xxReturnMsg)
  • ​A custom HTTP header response variable
    

​Here is the PL/SQL code for the Handler:

I have documented the code to describe how each of the variables and HTTP value are being accesses/set. Now let's see what a call to the above service would look like using PostMan:

Conclusion

Hopefully this helped describe the options available to you when dealing with custom and standard variables available for your use in ORDS.