7.1 About Oracle RESTful Services in Oracle APEX

This section introduces RESTful Services as implemented by Oracle REST Data Services (ORDS) and provides clarification on the terminology used within APEX 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 Oracle APEX 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 APEX configuration includes Oracle REST Data Services (ORDS) 20.x or later.
• 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 APEX Administration Guide

Support for Existing RESTful Services from Earlier Releases

Prior to APEX release 18.1, the metadata for APEX-based RESTful Services were defined in the core APEX metadata repository. APEX-based REST Services were desupported in APEX release 22.1. ORDS release 21.4.2 and later includes migration scripts that enable you to upgrade any remaining APEX-based REST Services to ORDS-based Services. To learn more, see Migration of Oracle APEX Restful Service Modules in Oracle REST Data Services Release Notes.

See Also:

Downloading, Configuring and Installing Oracle REST Data Services in Oracle REST Data Services Installation and Configuration 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 APEX App Builder User’s Guide

7.1.7 RESTful Services Terminology

Terminology used in Oracle APEX 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.