Oracle REST Data Services: Implicit Parameters

07/01/2019

Introduction

Oracle REST Data Services (ORDS) understands two kinds of named parameter binds that can be used in the source of a resource handler statement:

Explicit - Explicit parameters are defined by the Resource Handler author using the ords.define_parameter API procedure. They can be used to map request headers to bind parameters and also used to bind outbound values to response headers.
Implicit - Implicit parameters are defined by ORDS, they’re automically available to use, rather than needing to be explicitly declared. Unfortunately till recently we haven’t done a great job of documenting these implicit parameters.

Having said that, since ORDS 18.3.0, we have added documentation for all the implicit parameters that ORDS defines, here’s a direct link:

https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/18.3/aelig/implicit-parameters.html

Read on to learn more about the most important implicit parameters.

Commonly used Implicit Parameters

Identifying the authenticated user

The :current_user parameter is analogous to the value of the OWA CGI REMOTE_USER environment variable. It tells you the identity of the user that was authenticated for the current request. If no user was authenticated then this value will be null. See my blog post for more detail on this.

Reading the body of a request

The :body and :body_text parameters provide access to the body of the current HTTP request.

:body provides the data as an instance of a temporary BLOB datatype. This is useful when dealing with binary payloads such as image and video data.

:body_text provides the data as an instance of a temporary CLOB datatype. This is useful when dealing with textual payloads such as JSON and XML data.

The :content_type parameter provides the value of the Content-Type request header. If no Content-Type header is provided in the request the value is null.

Setting the response status code

PL/SQL based resource handlers such as POST and DELETE handlers will typically want to set the HTTP status code for a response. The easiest way to do this is to use the :status_code implicit parameter:

1
2
3
4
5
6


    begin
      /* Process the request */
      ...
      /* Set the response status code */
      :status_code := 201;
    end;

ORDS will automically set the status code of the HTTP response to the value of the :status_code bind.

Delegating Response Generation

In REST APIs it is idiomatic for POST and PUT methods to return the stored representation of the created/updated resource. Thus it is convenient to be able to delegate to the GET handler of the resource to produce the representation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


    declare
     l_created_resource_path varchar2(255);
    begin
      /* Process the request */
      ...
      l_created_resource := ... /* compute location of new resource */
      :status_code := 201;
      /* Ask ORDS to do a GET against following location
         and return that as the response for the request */
      :forward_location := l_created_resource_path;
    end;

ORDS will automatically internally perform a GET request against the location specified by the value of the :forward_location parameter and will return that as the response for the request.

Optional Parameters

In addition to the set of documented always available implicit parameters there is a second set of quasi-implicit parameters. Any parameter appearing the in the query string of a URL can be automatically dereferenced as a bind parameter, without requiring an explicit ords.define_parameter call. I cover this in my blog post on the ORDS Route Pattern syntax.

Reserved Query Parameter Names

Note that ORDS reserves a small set of query parameter names for it’s own use, these are: page, offset, limit and q.

Variously Noted