1/19

Contents

List of Examples

List of Figures

List of Tables

Title and Copyright Information

Preface

• Audience
• Documentation Accessibility
• Related Documents
• Conventions
• Third-Party License Information

Changes in This Release for Oracle REST Data Services Installation, Configuration, and Development Guide

• Changes in Oracle REST Data Services Release 17.4
  • New Features
  • Deprecated Features

1 Installing Oracle REST Data Services

• 1.1 About Oracle REST Data Services
• 1.2 Understanding the Installation Process
  • 1.2.1 Supported Java EE Application Servers
  • 1.2.2 System Requirements
  • 1.2.3 About Installing Oracle REST Data Services
• 1.3 Configuring and Installing Oracle REST Data Services
  • 1.3.1 About Using the Command-Line Interface
  • 1.3.2 About the Database Users Used by Oracle REST Data Services
  • 1.3.3 Privileges Granted by Oracle REST Data Services
  • 1.3.4 Downloading, Configuring and Installing Oracle REST Data Services
    • 1.3.4.1 Advanced Installation Using Command-Line Prompts
      • 1.3.4.1.1 Descriptions for Advanced Installation Prompts
    • 1.3.4.2 Silent Installation Using a Parameter File
      • 1.3.4.2.1 Parameters for Installing in Silent Mode
    • 1.3.4.3 Validating the Oracle REST Data Services Installation
    • 1.3.4.4 If You Want to Reinstall or Uninstall (Remove) Oracle REST Data Services
  • 1.3.5 Using SQL Developer Oracle REST Data Services Administration (Optional)
    • 1.3.5.1 About SQL Developer Oracle REST Data Services Administration
    • 1.3.5.2 Configuring an Administrator User
  • 1.3.6 Using OAuth2 in Non-HTTPS Environments
• 1.4 Running in Standalone Mode
  • 1.4.1 Starting in Standalone Mode
    • 1.4.1.1 Converting a Private Key to DER (Linux and Unix)
  • 1.4.2 Stopping the Server in Standalone Mode
  • 1.4.3 Configuring a Doc Root for Non-Application Express Static Resources
• 1.5 Deploying to Oracle WebLogic Server
  • 1.5.1 About Oracle WebLogic Server
  • 1.5.2 Downloading, Installing, and Configuring Oracle REST Data Services
  • 1.5.3 Configuring Oracle Application Express Images
  • 1.5.4 Launching the Administration Server Console
  • 1.5.5 Installing the Oracle WebLogic Server Deployment
  • 1.5.6 Configuring WebLogic to Handle HTTP Basic Challenges Correctly
  • 1.5.7 Verifying the State and Health of ords and i
• 1.6 Deploying to GlassFish Server
  • 1.6.1 About GlassFish Server
  • 1.6.2 Downloading, Installing, and Configuring Oracle REST Data Services
  • 1.6.3 Configuring Oracle Application Express Images
  • 1.6.4 Launching the Administration Server Console
  • 1.6.5 Installing the GlassFish Server Deployment
• 1.7 Deploying to Apache Tomcat
  • 1.7.1 About Apache Tomcat
  • 1.7.2 Downloading, Installing, and Configuring Oracle REST Data Services
  • 1.7.3 Configuring Oracle Application Express Images
  • 1.7.4 Installing the Apache Tomcat Deployment
• 1.8 Upgrading Oracle REST Data Services
• 1.9 Using a Bequeath Connection to Install, Upgrade, Validate, or Uninstall Oracle REST Data Services

2 Configuring Oracle REST Data Services (Advanced)

• 2.1 Configuring Multiple Databases
  • 2.1.1 About the Request URL
  • 2.1.2 Configuring Additional Databases
  • 2.1.3 Routing Based on the Request Path Prefix
    • 2.1.3.1 Example of Routing Based on the Request Path Prefix
  • 2.1.4 Routing Based on the Request URL Prefix
    • 2.1.4.1 Example of Routing Based on the Request URL Prefix
• 2.2 Using the Multitenant Architecture with Oracle REST Data Services
  • 2.2.1 Understanding the Installation Choices
  • 2.2.2 Installing Oracle REST Data Services into a CDB
  • 2.2.3 Upgrading Oracle REST Data Services in a CDB Environment
  • 2.2.4 Making All PDBs Addressable by Oracle REST Data Services (Pluggable Mapping)
  • 2.2.5 Uninstalling Oracle REST Data Services in a CDB Environment
• 2.3 Support for Oracle RAC Fast Connection Failover
• 2.4 Configuring Security, Caching, Pre- and Post Processing, Environment, and Excel Settings
• 2.5 Configuring REST-Enabled SQL Service Settings
• 2.6 Configuring the Maximum Number of Rows Returned from a Query
• 2.7 Configuring the Custom Error Pages
• 2.8 Developing RESTful Services for Use with Oracle REST Data Services

3 Developing Oracle REST Data Services Applications

• 3.1 Introduction to Relevant Software
  • 3.1.1 About Oracle Application Express
  • 3.1.2 About RESTful Web Services
• 3.2 Getting Started with RESTful Services
  • 3.2.1 RESTful Services Terminology
  • 3.2.2 About Request Path Syntax Requirements
  • 3.2.3 "Getting Started" Documents Included in Installation
  • 3.2.4 About cURL and Testing RESTful Services
  • 3.2.5 Automatic Enabling of Schema Objects for REST Access (AutoREST)
    • 3.2.5.1 Examples: Accessing Objects Using RESTful Services
      • 3.2.5.1.1 Get Schema Metadata
      • 3.2.5.1.2 Get Object Metadata
      • 3.2.5.1.3 Get Object Data
      • 3.2.5.1.4 Get Table Data Using Paging
      • 3.2.5.1.5 Get Table Data Using Query
      • 3.2.5.1.6 Get Table Row Using Primary Key
      • 3.2.5.1.7 Insert Table Row
      • 3.2.5.1.8 Update/Insert Table Row
      • 3.2.5.1.9 Delete Using Filter
      • 3.2.5.1.10 Post by Batch Load
    • 3.2.5.2 Filtering in Queries
      • 3.2.5.2.1 FilterObject Grammar
      • 3.2.5.2.2 Examples: FilterObject Specifications
    • 3.2.5.3 Auto PL/SQL
      • 3.2.5.3.1 Method and Content Type Supported for Auto Enabling PL/SQL Objects
      • 3.2.5.3.2 Auto-Enabling the PL/SQL Objects
      • 3.2.5.3.3 Generating the PL/SQL Endpoints
      • 3.2.5.3.4 Resource Input Payload
      • 3.2.5.3.5 Resource Payload Response
      • 3.2.5.3.6 Function Return Value
  • 3.2.6 Manually Creating RESTful Services Using SQL and PL/SQL
    • 3.2.6.1 About Oracle REST Data Services Mechanisms for Passing Parameters
      • 3.2.6.1.1 Using JSON to Pass Parameters
      • 3.2.6.1.2 Using Route Patterns to Pass Parameters
      • 3.2.6.1.3 Using Query Strings for Optional Parameters
    • 3.2.6.2 Using SQL/JSON Database Functions
      • 3.2.6.2.1 Inserting Nested JSON Objects into Relational Tables
      • 3.2.6.2.2 Generating Nested JSON Objects from Hierachical Relational Data
      • 3.2.6.2.3 Testing the RESTful Services
  • 3.2.7 About Working with Dates Using Oracle REST Data Services
    • 3.2.7.1 About Datetime Handling with Oracle REST Data Services
    • 3.2.7.2 About Setting the Time Zone
    • 3.2.7.3 Exploring the Sample RESTful Services in Application Express (Tutorial)
• 3.3 Configuring Secure Access to RESTful Services
  • 3.3.1 Authentication
    • 3.3.1.1 First Party Cookie-Based Authentication
    • 3.3.1.2 Third Party OAuth 2.0-Based Authentication
      • 3.3.1.2.1 Two-Legged and Three-Legged OAuth Flows
  • 3.3.2 About Privileges for Accessing Resources
  • 3.3.3 About Users and Roles for Accessing Resources
  • 3.3.4 About the File-Based User Repository
  • 3.3.5 Tutorial: Protecting and Accessing Resources
    • 3.3.5.1 OAuth Flows and When to Use Each
    • 3.3.5.2 Assumptions for This Tutorial
    • 3.3.5.3 Steps for This Tutorial
• 3.4 About Oracle REST Data Services User Roles
  • 3.4.1 About Oracle Application Express Users and Oracle REST Data Services Roles
    • 3.4.1.1 Granting Application Express Users Oracle REST Data Services Roles
    • 3.4.1.2 Automatically Granting Application Express Users Oracle REST Data Services Roles
  • 3.4.2 Controlling RESTful Service Access with Roles
    • 3.4.2.1 About Defining RESTful Service Roles
    • 3.4.2.2 Associating Roles with RESTful Privileges
• 3.5 Authenticating Against WebLogic Server and GlassFish User Repositories
  • 3.5.1 Authenticating Against WebLogic Server
    • 3.5.1.1 Creating a WebLogic Server User
    • 3.5.1.2 Verifying the WebLogic Server User
  • 3.5.2 Authenticating Against GlassFish
    • 3.5.2.1 Creating a GlassFish User
    • 3.5.2.2 Verifying the GlassFish User
• 3.6 Integrating with Existing Group/Role Models
  • 3.6.1 About role-mapping.xml
    • 3.6.1.1 Parameterizing Mapping Rules
    • 3.6.1.2 Dereferencing Parameters
    • 3.6.1.3 Indirect Mappings
• 3.7 Using the Oracle REST Data Services PL/SQL API
  • 3.7.1 Creating a RESTful Service Using the PL/SQL API
  • 3.7.2 Testing the RESTful Service

4 REST-Enabled SQL Service

• 4.1 REST-Enabled SQL Service Terminology
• 4.2 Configuring the REST-Enabled SQL Service
• 4.3 Using cURL with REST-Enabled SQL Service
• 4.4 Getting Started with the REST-Enabled SQL Service
  • 4.4.1 REST-Enabling the Oracle Database Schema
  • 4.4.2 REST-Enabled SQL Authentication
  • 4.4.3 REST-Enabled SQL Endpoint
• 4.5 REST-Enabled SQL Service Examples
  • 4.5.1 POST Requests Using application/sql Content-Type
    • 4.5.1.1 Using a Single SQL Statement
    • 4.5.1.2 Using a File with cURL
    • 4.5.1.3 Using Multiple SQL Statements
  • 4.5.2 POST Requests Using application/json Content-Type
    • 4.5.2.1 Using a File with cURL
    • 4.5.2.2 Specifying the Limit Value in a POST Request for Pagination
    • 4.5.2.3 Specifying the Offset Value in a POST Request for Pagination
    • 4.5.2.4 Defining Binds in a POST Request
    • 4.5.2.5 Specifying Batch Statements in a POST Request
  • 4.5.3 Example POST Request with DATE and TIMESTAMP Format
  • 4.5.4 Data Types and Formats Supported
• 4.6 REST-Enabled SQL Request and Response Specifications
  • 4.6.1 Request Specification
  • 4.6.2 Response Specification
• 4.7 Supported SQL, SQL*Plus, and SQLcl Statements
  • 4.7.1 Supported SQL Statements
  • 4.7.2 Supported PL/SQL Statements
  • 4.7.3 Supported SQL*Plus Statements
    • 4.7.3.1 Set System Variables
    • 4.7.3.2 Show System Variables
  • 4.7.4 Supported SQLcl Statements

5 NoSQL and Oracle REST Data Services

• 5.1 About NoSQL and Oracle REST Data Services
  • 5.1.1 Technology Environment
  • 5.1.2 Typical Oracle REST Data Services Input and Output
• 5.2 NoSQL Store Installation and Registration
• 5.3 Adding and Removing a NoSQL Store for Use with Oracle REST Data Services
• 5.4 NoSQL REST Services
  • 5.4.1 Metadata Services
    • 5.4.1.1 Read Metadata (GET)
  • 5.4.2 Data Services
    • 5.4.2.1 Read Data (GET)
    • 5.4.2.2 Idempotent Write (PUT)
    • 5.4.2.3 Write (POST)
    • 5.4.2.4 Delete (DELETE)
  • 5.4.3 DDL Services
    • 5.4.3.1 Create/Update (POST)
    • 5.4.3.2 Drop (POST)
    • 5.4.3.3 Poll (GET)
  • 5.4.4 Common Parameters
    • 5.4.4.1 Parameters to Skip Results and Limit the Number of Results
    • 5.4.4.2 Parameters to Specify Query Conditions
    • 5.4.4.3 Parameters to Specify Direction (Order), and Consistency and Durability Guarantees

6 Oracle REST Data Services PL/SQL Package Reference

• 6.1 ORDS.CREATE_ROLE
• 6.2 ORDS.CREATE_SERVICE
• 6.3 ORDS.DEFINE_HANDLER
• 6.4 ORDS.DEFINE_MODULE
• 6.5 ORDS.DEFINE_PARAMETER
• 6.6 ORDS.DEFINE_PRIVILEGE
• 6.7 ORDS.DEFINE_SERVICE
• 6.8 ORDS.DEFINE_TEMPLATE
• 6.9 ORDS.DELETE_MODULE
• 6.10 ORDS.DELETE_PRIVILEGE
• 6.11 ORDS.DELETE_ROLE
• 6.12 ORDS.DROP_REST_FOR_SCHEMA
• 6.13 ORDS.ENABLE_OBJECT
• 6.14 ORDS.ENABLE_SCHEMA
• 6.15 ORDS.PUBLISH_MODULE
• 6.16 ORDS.RENAME_MODULE
• 6.17 ORDS.RENAME_PRIVILEGE
• 6.18 ORDS.RENAME_ROLE
• 6.19 ORDS.SET_MODULE_ORIGINS_ALLOWED
• 6.20 ORDS.SET_URL_MAPPING

7 OAUTH PL/SQL Package Reference

• 7.1 OAUTH.CREATE_CLIENT
• 7.2 OAUTH.DELETE_CLIENT
• 7.3 OAUTH.GRANT_CLIENT_ROLE
• 7.4 OAUTH.RENAME_CLIENT
• 7.5 OAUTH.REVOKE_CLIENT_ROLE
• 7.6 OAUTH.UPDATE_CLIENT

A Oracle REST Data Services Database Type Mappings

• A.1 Oracle Built-in Types
• A.2 Handling Structural Database Types
• A.3 Oracle Geospacial Encoding
• A.4 Enabling Database Mapping Support

B About the Oracle REST Data Services Configuration Files

• B.1 Locating Configuration Files
• B.2 Setting the Location of the Configuration Files
• B.3 Understanding the Configuration Folder Structure
• B.4 Understanding the Configuration File Format
  • B.4.1 Understanding the url-mapping.xml File Format
• B.5 Understanding Configurable Parameters

C Troubleshooting Oracle REST Data Services

• C.1 Enabling Debug Tracing
• C.2 Enabling Detailed Request Error Messages
• C.3 Configuring Application Express Static Resources with Oracle REST Data Services

D Creating an Image Gallery

• D.1 Before You Begin
  • D.1.1 About URIs
  • D.1.2 About Browser Support
  • D.1.3 Creating an Application Express Workspace
• D.2 Creating the Gallery Database Table
• D.3 Creating the Gallery RESTful Service Module
• D.4 Trying Out the Gallery RESTful Service
• D.5 Creating the Gallery Application
• D.6 Trying Out the Gallery Application
• D.7 Securing the Gallery RESTful Services
  • D.7.1 Protecting the RESTful Services
  • D.7.2 Modifying the Application to Use First Party Authentication
• D.8 Accessing the RESTful Services from a Third Party Application
  • D.8.1 Creating the Third Party Developer User
  • D.8.2 Registering the Third Party Application
  • D.8.3 Acquiring an Access Token
  • D.8.4 Using an Access Token
  • D.8.5 About Browser Origins
  • D.8.6 Configuring a RESTful Service for Cross Origin Resource Sharing
  • D.8.7 Acquiring a Token Using the Authorization Code Protocol Flow
    • D.8.7.1 Registering the Client Application
    • D.8.7.2 Acquiring an Authorization Code
    • D.8.7.3 Exchanging an Authorization Code for an Access Token
    • D.8.7.4 Extending OAuth 2.0 Session Duration
  • D.8.8 About Securing the Access Token

Index