Oracle REST Data Services: Options for your Web Services

Copyright © 2014 Oracle and/or its affiliates. All rights reserved. |
ORDSRESTServicesMenu
https://oracle.com/rest
Jeff Smith
Senior Principal Product Manager
Jeff.d.smith@oracle.com || @thatjeffsmith
Database Tools, Oracle Corp

Copyright © 2016, Oracle and/or its affiliates. All rights reserved. |
Oracle
REST
Data
Services
2
Formerly Known as the APEX Listener

Publishing Web Services for your Oracle Database
• How it works
• Mapping service templates to database transactions
• Your database workload implementation options

ORDS Service Offerings
• No Code, Automatic
• Code, You Define Everything
• Ad Hoc
• Management API
• Everything is $0

GET https://host/ords/human/peeps/ SELECT *
FROM
EMPLOYEES
Anatomy of an ORDS Request & Response
HTTP/1.1 200 OK
{ "employee_id": 100,
"first_name": "Kris"
,"last_name": "Rice",
, “email": “krisrice@oracle.com",
{json}
URI SQL & PLSQLMap & BindHTTP Request
HTTP Response Transform to JSON SQL Result Set / Standard OUT
Oracle REST Data Services

ORDS Typical Architecture
• Standard webserver layout
• Implements Java Servlet
• Deploys to Tomcat or WLS
• Also Supported:
Standalone mode (Jetty)
Tomcat, WLS
ORDS
Apache
Static Files
-HTML, CSS, JS
/ords/…
/db1/hr/emp/
JSON
Binary
HTML
…
HTTP(s)
Results
JDBC
pool1 pool2 pool3
Request
JDBC JDBC

ORDS Standalone Deployments
• ORDS running as a OS process
• Eclipse Jetty Webserver
& Servlet Container
• Supported for Production
• Offers much fewer control,
configuration, and management
features
ORDS
w/Embedded
Jetty
Static Files
-HTML, CSS, JS
/db1/hr/emp/
JSON
Binary
HTML
…
HTTP(s)
Results
JDBC
pool1 pool2 pool3
Request
JDBC JDBC

How ORDS Gets to your Oracle Database
• Connection Pools
• Default Size: 10
• 1st pool defaults to ords/
• Proxy Connects Enabled Schemas

• ords – ords.war, Java servlet
• hr – schema (alias!), service handler code runs as this user
• ukoug – module
• media/:id – template
• Methods supported
– GET, PUT, POST, DELETE
Mapping the URI from a HTTP request

Getting Started
1. Deploy ORDS, Map Database(s)
2. REST Enable Schema
3. Publish Services
SECURITY IS NOT AN AFTERTHOUGHT – Secure All Endpoints!

How ORDS Uses a REST Enabled Schema
• Services are defined per schema
• Services are executed in the database as that user

Ok, Now What?
Time To Start Deploying Services
• Auto REST
• RESTful Services

Tooling Support
Oracle SQL Developer
• Full ORDS Integration
• Develop RESTful Services
• REST Enable Objects
• Manage ORDS Roles and
Privileges

Full Command-Line Interface & PL/SQL API

Choose Your Own Adventure!
AUTO REST Advantages
• CRUD APIs, no SQL to write
• Single ORDS package call to
create
• Maintained by US
• Feature Packed
• Optimized
RESTful Service Advantages
• You’re in charge
• Inputs, outputs, error handling,
response codes, formatting
• Full access to SQL/PLSQL
• Easily exported, source
controlled
• Transparent

Automatic – ORDS Owns the Database Work
• Auto REST Table
– Full CRUD API, Data Loading, Metadata (DESC)
• Auto REST View
– Read interface only (GET)
• Auto PL/SQL (RPC)
– POST to execute stored PL/SQL
– We accept {json} in, map to input params, grab output and {json} out

AUTO REST: TABLE =>
• GET
• PUT
• POST
• DELETE
• DESC
• DOCS
/ords/hr/employees
/ords/hr/employees/
/ords/hr/employees/:id

Auto enablement of RESTful request
modules – User Interface
Exposes these operations
• Schema level Metadata
• Table Metadata
• Get ( Select )
• Query ( Filtering/Order/ASOF )
• Insert
• Update
• Delete
• Load CSV

Querying the Table
• All rows /
• One row /:id – PK Value
– No PK, default to ROWID
– Multi-column PK /x,y,z
• Some rows /?q={json}

Update a Row
METHOD : PUT /:PK
REQUEST BODY : JSON
RESPONSE: 200 OK
• Location (Header)
• JSON (Body)
Table Columns in the POST body
{“column_name” : column_value }

PL/SQL API Access Only?
• No worries!
• We auto-magically handle PL/SQL too
• RPC -> POST via HTTPS /ords/hr/procedureA
• Responses & Results (OUTs/RETURNs/REFCURSORs), in {JSON}

Remote Procedure Call over
HTTP(S) via POST
ORDS takes parameters as JSON, executes PL/SQL,
grabs output, sends back down as JSON
OUT INTEGER & SYS_REFCURSOR
{
"total_payroll": 631230,
"peeps_numbers": [
{
"id": 81,
"name": "Dummy4",
"salary": 0,
"hire_date": "2017-06-20T13:29:00Z"
},
{
"id": 65,
"name": "Bart",
"salary": 0,
"hire_date": "2017-06-20T13:29:00Z"
},
{
"id": 79,
…
}

Execute PL/SQL TABLE API
Execute, REFCURSOR RETURN

Modules
• A collection of RESTful Services
• Can be secured as a group with a privilege
• Can be published or hidden as a group
• Can set a default response pagination size

URI Templates
/ords/hr/test2/employees
/ords/hr/test2/employees/
/ords/hr/test2/employees/:id
SQL & PLSQL

Handlers – provide the code and define the response

Source Types – Determines How We Format Responses
• Collection Query
– Multiple records/paging
• Collection Query Item
– Single record only/no paging
• Query
– Multiple records/paging/no metadata
• Query One Row
– Single records only/no paging/no metadata

Source Types – Determines How We Handle Responses
• Feed
– Multiple records/paging
– First column auto-generates $link
• PL/SQL
– Executes PL/SQL Block
• Media Resource
– First Column sets Mime Type
– Second Column sets raw content (no json-ification)
Feed Source Type

POST: Upload a file, store as a BLOB in a TABLE

The Response

The RESTful Service (POST – PL/SQL Block)

GET: Print List of Rows as Links
select title
,content_type
,id "$uri"
from gallery
order by title

Helpers for your Code, Automatic :Binds
• POST request body
– :body (BLOB) or :body_text (CLOB)
• Who is accessing the end point
– Authenticated user is mapped to :current_user
• HTTP Response Status :status_code & Redirects :forward_location
• :content_type, :fetch_size, :fetch_offset, :row_count, :page_offset

RESTful Services Source Code

OpenAPI Support {Swagger} – AUTO & RESTful Services

• Disabled by default
• AUTH by user with sql dev priv or via DB
curl -X POST
http://localhost:8080/ords/hr/_/sql
-H 'authorization: Basic SFI6b3JhY2xl’
-H 'cache-control: no-cache’
-H 'content-type: application/sql’
-H 'postman-token: 23a49622-a195-cb76-0606-358f3e371cdd’
-d 'SELECT first_name, last_name, department_name
FROM hr.employees, hr.departments
where employees.department_id = departments.department_id'
Execute SQL via POST
_/sql/ Endpoint

APEX Support
Your app can push/pull data
from another Database via
HTTPS vs DB_LINKs

2019…REST APIs for the Database!
• Database Creation Assistant
• Data Pump (Export Only v1)
• PDB Lifecyle
• Monitoring
– Objects, ASH, RTSM

Clone a PDB, Get a list of Wait Events, Read the Alert Log…

ORDS Resources
• Blogs
• Videos
• GitHub Examples
• Articles
– UKOUG Scene Why REST, and What’s in it or Me?
– Oracle Mag AUTO REST & REST Enabled SQL

Oracle REST Data Services: Options for your Web Services

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Oracle REST Data Services: Options for your Web Services

Similar to Oracle REST Data Services: Options for your Web Services (20)

More from Jeff Smith

More from Jeff Smith (20)

Recently uploaded

Recently uploaded (20)

Oracle REST Data Services: Options for your Web Services

Editor's Notes