JMJ CLOUD
  • Home
  • Projects
  • Blog
  • About Us
  • Contact Us

Our Blog

ORDS HTTP Headers and Variables Revisited for ORDS3

9/8/2016

1 Comment

 

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.
Picture
  • 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
Picture
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:
Picture
   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.
Picture
Service Module, Template & Handler
The handler for the template has 4 parameters:
Picture
  • 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.
1 Comment
Steven Stowers
11/29/2018 05:33:14 pm

Finally working for a client who embraces REST services/ORDS. Your example above was a huge help ion getting me started.

Thank you

Reply

Your comment will be posted after it is approved.


Leave a Reply.

    RSS Feed

    Popular Posts

    - APEX Dog Food
    - Cloud ERP & APEX Mashup
    - Modernizing EBS with APEX
    - Easy APEX_WEB_SERVICE
    - Running APEX in RDS
    - ORDS What & Why?

    Categories

    All
    APEX
    AWS
    Fusion Cloud ERP
    INTEGRATION
    MS GRAPH
    OCI
    ORDS
    PaaS
    RAD
    REST
    SOAP

    Archives

    February 2021
    January 2021
    October 2020
    September 2020
    June 2020
    May 2020
    April 2020
    February 2020
    January 2020
    October 2019
    September 2019
    August 2019
    July 2019
    June 2019
    April 2019
    March 2019
    February 2019
    January 2019
    December 2018
    November 2018
    October 2018
    September 2018
    August 2018
    July 2018
    June 2018
    May 2018
    April 2018
    March 2018
    February 2018
    January 2018
    September 2017
    August 2017
    July 2017
    June 2017
    February 2017
    January 2017
    December 2016
    November 2016
    October 2016
    September 2016
    August 2016
    July 2016

Company

About
Contact
Blog
  • Home
  • Projects
  • Blog
  • About Us
  • Contact Us