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.
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
- 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.
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’.
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).
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.
Not much changed on the outbound side, there are three key variables you need to be aware of:
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:
l_client_system := owa_util.get_cgi_env('XX-CLIENT-SYSTEM');
Adding a Parameter:
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
- 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
- A custom HTTP header response variable
Here is the PL/SQL code for the Handler: