7.1 About Oracle RESTful Services in Application Express

This section introduces RESTful Services as implemented by Oracle REST Data Services (ORDS) and provides clarification on the terminology used within Application Express and other Oracle tools to reference the different components that make up a RESTful Service.

You use Resource Modules, Resource Templates, and Resource Handlers, to configure RESTful Services as implemented by Oracle REST Data Services (ORDS).

• RESTful Service Configuration Requirements
  Configuration requirements for exposing RESTful Services to external systems.
• REST and RESTful Services
  Representational State Transfer (REST) is a way of providing interoperability between computer systems over the Internet. You can define the RESTful services to enable the querying and manipulation of data without the need for direct access to the underlying data store.
• Resource Modules
  A Resource Module is a container that groups a set of related RESTful Services together.
• Resource Templates
  A Resource Template defines an individual service that can be called. Resource Templates are contained in Resource Modules.
• Resource Handlers
  Each Resource Handler implements one (and only one) HTTP operation. It is important to understand how Resource Handler implementations are mapped to traditional Create, Read, Update, Delete (CRUD) operations.
• Example RESTful Service
  Use Resource Modules, Resource Templates, and Resource Handlers, to configure RESTful Services as implemented by Oracle REST Data Services (ORDS).
• RESTful Services Terminology
  Terminology used in Application Express and other Oracle tools to reference the different components that make up a RESTful Service.

7.1.1 RESTful Service Configuration Requirements

Configuration requirements for exposing RESTful Services to external systems.

You must meet the following requirements for the RESTful Service utility to be available and function:

• Your Oracle Application Express configuration includes Oracle REST Data Services (ORDS) 19.x or later.

  Note:

  The Oracle XML DB HTTP Server with the embedded PL/SQL gateway and Oracle HTTP Server with mod_plsql do NOT support RESTful Services.

• An administrator has enabled RESTful Services either at the workspace or instance-level as described in Controlling RESTful Services for a Workspace and Enabling RESTful Services for an Instance in Oracle Application Express Administration Guide

Support for Existing RESTful Services from Earlier Releases

Prior to Oracle Application Express release 18.1, the metadata for Application Express based RESTful Services are defined in the core Oracle Application Express metadata repository.

As Oracle moves toward a unified RESTful Services repository based on Oracle REST Data Services (ORDS), you need to migrate RESTful Services previously defined in Oracle Application Express to the ORDS-based repository.

The behavior of Oracle REST Data Services in earlier releases differs from the current release:

• When running Oracle Application Express release 18.1 with Oracle REST Data Services prior to release 17.4.1, only the traditional Application Express based REST Services console is available. You can continue to create and maintain Application Express based RESTful services and they will be stored in the traditional Oracle Application Express metadata repository.

• When running Oracle Application Express release 18.1 with Oracle REST Data Services (ORDS) release 19.1 or later and the workspace currently contains Application Express based RESTful Services.

  • You only have read-only access to the traditional Application Express based RESTful Service pages. The current services continue to work, however, you are not be able to create new or edit existing Application Express based RESTful Services.

    Note:

    Clicking the Migrate to ORDS RESTful Services button migrates all existing Application Express-based RESTful services within the workspace to the ORDS metadata repository.

• When running Oracle Application Express release 18.1 with Oracle REST Data Services (ORDS) release 19.1 or later and the workspace currently does not contain any Application Express based RESTful Services, you are navigated to the new Oracle REST Data Services (ORDS) based RESTful Services pages and will not have access to the traditional Application Express based RESTful Services screens.

See Also:

"Installing Oracle REST Data Services" in Oracle REST Data Services Installation, Configuration, and Development Guide

7.1.2 REST and RESTful Services

Representational State Transfer (REST) is a way of providing interoperability between computer systems over the Internet. You can define the RESTful services to enable the querying and manipulation of data without the need for direct access to the underlying data store.

A service is described as RESTful when it conforms to the tenets of REST. Although a full discussion of REST is outside the scope of this document, a RESTful Service has the following characteristics:

• A RESTful Service is modeled as a set of resources. Those resources are identified by URLs and accessed over the http or https web protocols.

• A small set of operations are used to manipulate resources (such as PUT, POST, GET, DELETE).

• RESTful Services are stateless. They maintain no connection between the client and serving computer systems, and no client context is stored between requests.

• Requests to a RESTful Service always elicit a response. This response is in the form of XML, JSON, HTML, or some other defined format.

• Responses provide details of some sort of alteration to the underlying data, error messages, and hypertext links to other related resources depending upon the operation.

REST resources use a stateless protocol with standard operations, so you can create reusable, underlying components that can be managed and updated without affecting the system, even while REST is running.

While consuming RESTful Services uses the standard HTTP operations, processing the data returned through a RESTful service is different. Oracle Application Express 19.2 provides a comprehensive set of components to make consuming RESTful services easier.

7.1.3 Resource Modules

A Resource Module is a container that groups a set of related RESTful Services together.

A Resource Module not only provides a way to identify the group uniquely, but also defines the unique Base Path used on a URL to access the set of services defined within the module.

In most cases, you must configure a Resource Module and a child Resource Template for each RESTful Service that you want your application to provide. You must also define a Resource Handler for each method associated with the same Resource Template. For example, to provide a method to return data and another to store data, you must define a Resource Handler for each operation.

Example 7-1 Resource Module

A Resource Module that enables you to access information about employees is named oracle.example.hr and the base path value for the service is /hr/ .

7.1.4 Resource Templates

A Resource Template defines an individual service that can be called. Resource Templates are contained in Resource Modules.

Each Resource Template defines a URI Pattern where it can be reached and implements at least one Resource Handler. A Resource Template may only implement one of each type of Resource Handler (GET, POST, PUT, DELETE) but can be configured not to implement all of them.

7.1.5 Resource Handlers

Each Resource Handler implements one (and only one) HTTP operation. It is important to understand how Resource Handler implementations are mapped to traditional Create, Read, Update, Delete (CRUD) operations.

GET

Retrieves a representation of a resource, equivalent to a SQL SELECT statement.

POST

Creates a new resource or adds a resource to a collection, equivalent to a SQL INSERT statement.

PUT

Updates the values an existing resource, equivalent to a SQL UPDATE statement.

DELETE

Deletes an existing resource, equivalent to a SQL DELETE statement.

7.1.6 Example RESTful Service

Use Resource Modules, Resource Templates, and Resource Handlers, to configure RESTful Services as implemented by Oracle REST Data Services (ORDS).

Example 7-2 Complete Resource Template

http://server.com/ords/anyco/hr/employees/7978

Where:

http://server_URL/ords_alias/schema_alias/base_path/module_base_path/URI_template/:bind_variable

A functionally complete Resource Template implements the ability to retrieve a specific employee's details by passing in the employee id. The Resource Template's URI Pattern is employees/:id. A Resource Handler is implemented using the GET operation and the following logic:

select empno, ename, dept from emp where empno = :id 

When calling the RESTful Service, access the service using the server path, base path and URI Template and providing a static value for the employee id as:

http://server.com/ords/anyco/hr/employees/7978

Server Path

http://server.com/

ORDS Alias

/ords/

Schema Alias

/anyco/

Base Path

/hr/

URI Template

employees/7978

When this particular URL is called using an HTTP GET, the service returns the result of the SQL Statement listed above. The format in which the data is returned depends upon the full definition of the Resource Handler.

Note:

A Resource Template is considered functionally incomplete if it does not implement at least one Resource Handler.

See Also:

• How to Create the ORDS Based RESTful Services Module Example

• Implementing Web Services in Oracle Application Express App Builder User’s Guide

7.1.7 RESTful Services Terminology

Terminology used in Application Express and other Oracle tools to reference the different components that make up a RESTful Service.

Base Path

A case sensitive base path that is used to access a RESTful Service. This base path for the module is appended to the server path and the Schema Alias for the underlying Oracle schema. The base path must be unique within the schema.

HTTP Operation

HyperText Transport Protocol (HTTP) defines standard methods that can be performed on resources: GET, POST, PUT, and DELETE.

Resource Handler

Provides the logic required to service a specific HTTP operation for a specific resource template.

Resource Module

A container that is used to group related RESTful Services together.

Resource Template

An individual RESTful Service that is able to service requests for some set of Universal Resource Identifiers (URIs ). The URI Pattern of the Resource Template defines the set of URIs.

RESTful Service

An HTTP web service that conforms to the tenets of the RESTful architectural style.

Schema Alias

When enabling an Oracle schema for use with RESTful services, an alias is required. The case sensitive Schema Alias is used to form the URL and appended to the server path prior to the Base Path and URI pattern.

URI pattern

A case sensitive path used to access the specific resource and can be either a Route Pattern or a URI Template. The URI Pattern for the resource is appended to the server path and Resource Module Base Path. The URI Pattern may also include a bind variable appended after a forward slash. This allows a value to be passed to the service as part of the URI. The bind variable syntax prefixes the variable name with a colon (:).

• Route Pattern - a pattern that focuses on decomposing the path portion of a URI into its component parts. For example, a pattern of /:object/:id? will
match /emp/101 (matches a request for the item in the emp resource with id of 101) and also match /emp/ (matches a request for the emp resource, because the :id parameter is annotated with the ? modifier, which indicates that the id parameter is optional).

• URI Template - a simple grammar that defines the specific patterns of URIs that a given resource template can handle. For example, the pattern employees/:id matches any URI whose path begins with employees/, such as employees/2560.