1/22

Contents

Pre-General Availability: 2017-09-04

List of Examples

List of Figures

List of Tables

Title and Copyright Information

Preface

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

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 Simple Installation Using a Parameters File
    • 1.3.4.2 Advanced Installation Using Command-Line Prompts
    • 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 Support for RAC Fast Connection Failover
• 2.3 Configuring Security, Caching, Pre- and Post Processing, Environment, and Excel Settings
• 2.4 Configuring REST Enabled SQL Service Settings
• 2.5 Configuring Maximum Number of Rows Returned from a Query
• 2.6 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 with ORDS
      • 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 ORDS
    • 3.2.7.1 About Datetime Handling with Oracle REST Data Services
    • 3.2.7.2 About Setting the Time Zone that ORDS Uses
    • 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
• 3.8 About REST Enabled SQL Service
  • 3.8.1 REST Enabled SQL Service Terminology
  • 3.8.2 Configuring REST Enabled SQL Service
  • 3.8.3 About cURL and Testing REST Enabled SQL Service
  • 3.8.4 Getting Started with REST Enabled SQL Service
    • 3.8.4.1 REST Enabling Oracle Database Schema
    • 3.8.4.2 The HTTPS POST Authentication
    • 3.8.4.3 HTTPS Post Request URL

4 NoSQL and Oracle REST Data Services

• 4.1 About NoSQL and Oracle REST Data Services
  • 4.1.1 Technology Environment
  • 4.1.2 Typical Oracle REST Data Services Input and Output
• 4.2 NoSQL Store Installation and Registration
• 4.3 Adding and Removing a NoSQL Store for Use with Oracle REST Data Services
• 4.4 NoSQL REST Services
  • 4.4.1 Metadata Services
    • 4.4.1.1 Read Metadata (GET)
  • 4.4.2 Data Services
    • 4.4.2.1 Read Data (GET)
    • 4.4.2.2 Idempotent Write (PUT)
    • 4.4.2.3 Write (POST)
    • 4.4.2.4 Delete (DELETE)
  • 4.4.3 DDL Services
    • 4.4.3.1 Create/Update (POST)
    • 4.4.3.2 Drop (POST)
    • 4.4.3.3 Poll (GET)
  • 4.4.4 Common Parameters
    • 4.4.4.1 Parameters to Skip Results and Limit the Number of Results
    • 4.4.4.2 Parameters to Specify Query Conditions
    • 4.4.4.3 Parameters to Specify Direction (Order), and Consistency and Durability Guarantees

5 ORDS PL/SQL Package Reference

• 5.1 ORDS.CREATE_ROLE
• 5.2 ORDS.CREATE_SERVICE
• 5.3 ORDS.DEFINE_HANDLER
• 5.4 ORDS.DEFINE_MODULE
• 5.5 ORDS.DEFINE_PARAMETER
• 5.6 ORDS.DEFINE_PRIVILEGE
• 5.7 ORDS.DEFINE_SERVICE
• 5.8 ORDS.DEFINE_TEMPLATE
• 5.9 ORDS.DELETE_MODULE
• 5.10 ORDS.DELETE_PRIVILEGE
• 5.11 ORDS.DELETE_ROLE
• 5.12 ORDS.DROP_REST_FOR_SCHEMA
• 5.13 ORDS.ENABLE_OBJECT
• 5.14 ORDS.ENABLE_SCHEMA
• 5.15 ORDS.PUBLISH_MODULE
• 5.16 ORDS.RENAME_MODULE
• 5.17 ORDS.RENAME_PRIVILEGE
• 5.18 ORDS.RENAME_ROLE
• 5.19 ORDS.SET_MODULE_ORIGINS_ALLOWED
• 5.20 ORDS.SET_URL_MAPPING

6 OAUTH PL/SQL Package Reference

• 6.1 OAUTH.CREATE_CLIENT
• 6.2 OAUTH.DELETE_CLIENT
• 6.3 OAUTH.GRANT_CLIENT_ROLE
• 6.4 OAUTH.RENAME_CLIENT
• 6.5 OAUTH.REVOKE_CLIENT_ROLE
• 6.6 OAUTH.UPDATE_CLIENT

A ORDS 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 HTTPS POST Request Examples for REST Enabled SQL Service

• C.1 POST Requests Using application/sql Content-Type
  • C.1.1 Using a Single SQL Statement
  • C.1.2 Using a File with cURL
  • C.1.3 Using Multiple SQL Statements
• C.2 POST Requests Using application/json Content-Type
  • C.2.1 Using a File with cURL
  • C.2.2 Specifying Limit Value in a POST Request for Pagination
  • C.2.3 Specifying Offset Value in a POST Request for Pagination
  • C.2.4 Defining Binds in a POST Request
• C.3 Example POST Request with DATE and TIMESTAMP Format
• C.4 Data Types and the Formats Supported

D Supported SQL, SQL*Plus and SQLcl Statements

• D.1 Supported SQL Statements
• D.2 Supported PL/SQL Statements
• D.3 Supported SQL*Plus Statements
  • D.3.1 Set System Variables
  • D.3.2 Show System Variables
• D.4 Supported SQLcl Statements

E Troubleshooting Oracle REST Data Services

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

F Development Tutorial: Creating an Image Gallery

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

G Using the Multitenant Architecture with Oracle REST Data Services

• G.1 Understanding the Installation Choices
• G.2 Installing Oracle REST Data Services into a CDB
• G.3 Upgrading Oracle REST Data Services in a CDB Environment
• G.4 Making All PDBs Addressable by Oracle REST Data Services (Pluggable Mapping)
• G.5 Uninstalling Oracle REST Data Services in a CDB Environment

H Getting Started with RESTful Services

• H.1 REST-Enable a Database Table
• H.2 Create a RESTful Service from a SQL Query
• H.3 Protect Resources
• H.4 Creating a RESTful Service through the Connections Navigator
  • H.4.1 Creating a Privilege under REST Data Services
  • H.4.2 Creating a Role
• H.5 Register an OAuth Client Application

Index