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_parameterAPI 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.
Read on to learn more about the most important implicit parameters.
Commonly used Implicit Parameters
Identifying the authenticated user
: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
: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.
: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
Setting the response status code
PL/SQL based resource handlers such as
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:
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
Delegating Response Generation
In REST APIs it is idiomatic for
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:
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
and will return that as the response for the request.
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: