Discusses Oracle’s implementation of REST and the terminology used to describe the various components of RESTful services.
This section introduces RESTful services as implemented by Oracle REST Data Services 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.
Common terms are:
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.
Resource Module: A container that is used to group related RESTful Services together.
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.
RESTful Service: An HTTP web service that conforms to the tenets of the RESTful architectural style.
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.
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.
Resource handler: Provides the logic required to service a specific HTTP operation for a specific resource template.
HTTP operation: HyperText Transport Protocol (HTTP) defines standard methods that can be performed on resources: GET, POST, PUT, and DELETE.
In general, for each RESTful service you want your application to provide, you must configure a Resource Module and a child Resource Template. For each method associated with the same Resource Template you must define a Resource Handler. For instance, if you want to provide a method to return data and another to store data, you must define a Resource Handler for each operation.
A Resource Module is a container used to group 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.
For example, a Resource Module that allows you to access information about employees may be named oracle.example.hr and a typical base path value for the service is /hr/ .
A Resource Template exists within the confines of a Resource Module and defines an individual service that can be called. Each Resource Template defines a URI Pattern where it can be reached and implements at least one Resource Handler. A given Resource Template may only implement one of each type of Resource Handler (GET, POST, PUT, DELETE) but may choose not to implement all of them.
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.
A Resource Template is considered functionally incomplete if it does not implement at least one Resource Handler.
An example of a functionally complete Resource Template might be one that implements the ability to retrieve a specific employee’s details by passing in the employee id. The Resource Templates URI Pattern looks like 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_address>>/<<schema_alias>>/hr/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.
See Also:
"Implementing Web Services" in Oracle Application Express App Builder User’s Guide
"How to Create the ORDS Based RESTful Services Module Example"
Parent topic: Enabling Data Exchange with RESTful Services