Previous Next JavaScript must be enabled to correctly display this content

## 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.

Parent topic: Enabling Data Exchange with RESTful Services

### 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

Parent topic: About Oracle RESTful Services in Oracle APEX

### 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.

Parent topic: About Oracle RESTful Services in Oracle APEX

### 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/` .

Parent topic: About Oracle RESTful Services in Oracle APEX

### 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.

Parent topic: About Oracle RESTful Services in Oracle APEX

### 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.

Parent topic: About Oracle RESTful Services in Oracle APEX

### 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://example.com/ords/anyco/hr/employees/7978

Where:

    http://example_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://example.com/ords/anyco/hr/employees/7978

Server Path
  `http://example.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

Parent topic: About Oracle RESTful Services in Oracle APEX

### 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`.

Parent topic: About Oracle RESTful Services in Oracle APEX