Oracle REST Data Services: POUG Edition

RESTful Web Services for
Oracle, POUG Edition
ORDS Product Manager
https://www.thatjeffsmith.com
@thatjeffsmith
Jeff Smith 🍻

• Presented originally in 2019 for POUG in Wroclav, Poland
• Pints with Oracle User Group
• Combines two of my favorite things, ORDS & Beer (beeords!)
• Please drink responsibly
• I have non-alcoholic slides/content on my blog
About these slides…
Jeff annoys people on twitter @thatjeffsmith

• product manager/storyteller
• I help/bother people online
• Working with Oracle Database since 1999
• Helping build database tools since 2001
• I ‘manage’ these products:
whoami

Today’s Agenda
• Introduction,Terms, & Definitions
• ORDS Architecture
• Building RESTfulWeb Services

Oracle
REST
Data
Services
Included for free with your Oracle Database!!!
oracle.com/rest

• REpresentational State Transfer
• Architectural Style for networked applications
• Communicates via HTTP, but..
• Using HTTP doesn’t magically make yourAPIs RESTful
Terms: REST

• Model things, not actions
• UseVERBS to interact,GET, PUT, POST, DELETE
• Stateless, so be sure to use LINKs to guide your users
POST beers/ =>Adds beer, responds w/link
GET beers/:id =>
RESTful Architecture
🍻

• Jay-Sun
• Not just for js!
• Skinnier than XML
• Flexible
• Link-friendly
Terms: {JSON}

{JSON} BonusTip!
Our tools make it easy to
get your database data in
JSON format, pretty or RAW
…

ORDS Features and Architecture
• How are RESTfulWeb Services defined
• How is ORDS deployed

• Automatic
• Your Code
• SQL on the fly
• ManagementAPIs
• SQLDevWeb
Delivery Options

GET https://host/ords/hr/beers/1 SELECT *
FROM UNTAPPD
WHERE ID = 1
HTTP/1.1 200 OK
{ “id": 100,
“name": “Bud Lite“,
“score": “0",
“comments": “yuck” }
{json}
URI SQL & PLSQL
Marshalls to Database
HTTP Request
HTTP Response Transforms to JSON SQL Result Set / Standard OUT
Oracle REST Data Services
ORDS: HTTP to SQL and back

• Webserver layout
• Java Servlet
• Tomcat orWLS
ORDS Architecture
Option #1
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

java –jar ords.war standalone
• Supported for production!
• ORDS is your webserver &
web listener for your
Oracle Databases
ORDS
Static Files
-HTML
, CSS,
JS
/db1/hr/emp/
JSON
Binary
HTML
…
HTTP(s)
Response
JDBC
pool1 pool2 pool3
Request
JDBC JDBC
ORDS Architecture
Option #2 : Standalone

• JDBC Conn Pools
• 1 Pool Per Database
• ORDS_PUBLIC_USER
• Proxy Connects
Enabled DB Users
ORDS & Database Communication

• PUT – HTTP Verb
• HTTPS – secure, encrypted version of HTTP (recommended!)
• Server:8080 – network location where ORDS is running
• ords – ords.war, Java servlet
• hr – schema alias, where service is defined
• examples – module, a collection of services
• beers/:id – template, defines the resource
Unwinding an ORDS Request
PUT https://server:8080/ords/hr/examples/beers/:id

Install & Start
ORDS
REST Enable
Application
SCHEMA
Publish RESTful
Service or REST
Enable object
1 2 3
Getting Started Steps

Step 1, Install ORDS
Video: I talk about the process, DO an install, use SQLDevWeb to build
a RESTfulWeb Service

• Services defined in schema
• Services executed as user
Step 2. REST Enable Schema
Services constrained by Database User:

• AUTO REST
• RESTful Services
Step 3. Define your Service

What RESTful Services could look like…

Twoje zdrowie! Or Cheers!
• UNTAPPD: my personal beer diary
• YES, these are MY pictures and MY comments
• Examples will show building REST APIs for my diary
🍻

Example – Beers w/pictures
SELECT beer_name,
brewery_name,
created_at,
photo_url "$pics",
comments
FROM untappd
WHERE photo_url IS NOT NULL
ORDER BY checkin_id DESC
GET all beers, with links to pictures

Example – Using Query String Parameters
?q={"beer_type":{"$like":"Stout%25"}}
SAME SQL, but…
ORDS injects the WHERE clause
for us.
No additional coding required!

Example: More Query String Parameters
?q={"beer_type":{"$like":"%25Tripel%25"}}

Filtering, Sorting and More
ORDS Handles the
SQL for you

Example: Generating Links
“$alias” => LINK

Example: Working w/JSON Data in the DB
BAD 

Escaping JSON 

Where/how to code your Services

Oracle SQL Developer
• Full ORDS Integration
• Develop RESTful Services
• REST Enable Objects
• Manage ORDS Roles and
Privileges
• Free! OS X,Windows, or Linux
IDE

DatabaseActions/SQLDev Web
• ORDS Single Page App
• Develop RESTful Services
• REST Enable Objects
• Manage ORDS Roles and
Privileges, OAuth2 Clients
• Free! Any major browser.
Browser

CLI & PL/SQL APIs
SQLcl Anywhere you can run PL/SQL

Or Application Express (APEX)
APEX is NOT required

Time to start building!

Home Brewing or Store Bought?
Your Code Someone Else’s

AUTOREST
• CRUD APIs, no SQL to write
• Single ORDS call to create
• Maintained by ORCL
• Feature Packed
• Optimized
RESTful Services
• You control:
• Inputs, outputs, error handling,
response codes, formatting
• Your SQL/PLSQL code
• Easily exported, source
controlled
• Transparent
Choose your own adventure!

AUTOREST Database Objects
TABLES
VIEWS
PROCEDURES
FUNCTIONS
PACKAGES

• Auto RESTTable
– Full CRUD API, Data Loading, Metadata (DESC)
• Auto RESTView
– Read interface (GET),Write (PUT+POST+DELETE w/PK onVIEW)
• Auto PL/SQL (RPC)
– POST to execute stored PL/SQL
– We accept {json} in, map to input params, grab output and {json} out
Automatic – ORDS owns the code

• GET
• PUT
• POST
• DELETE
• DESC
• DOCS
AutoREST Table /ords/hr/beers/
/ords/hr/beers/:PK

REST Enabling a TABLE

REST EnabledTABLE Swagger API Doc
• Table Metadata
• SELECT
Query Filtering/Order/ASOF SCN or Timestamp
• INSERT
• UPDATE
• DELETE
• BATCHLOAD

Two Quick AUTOREST TABLE Examples
1. GET one or more rows with a query
2. PUT updates to an existing row

• All rows /
• One row /:id – PKValue
– No PK, default to ROWID
– Multi-column PK /x,y,z
• Some rows /?q={json}
SELECT (GET)

METHOD : PUT /:PK
REQUEST BODY : JSON
RESPONSE: 200 OK
• Location (Header)
• JSON (Body)
UPDATE (PUT) : adding comments
REQUEST BODY
RESPONSE

We also support your PL/SQL Code!
1. Instant access to all of your application logic
2. ORDS ‘wrappers’ your existing PL/SQL with HTTPS

• POST /ords/hr/procA
• JSON Responses & Results (OUTs/RETURNs/REFCURSORs)
Accessing your PL/SQL Code, Automatically

Remote Procedure Call over HTTP (POST)

Remote Procedure Call over HTTP (POST)
Request
p(arg =>input)
Procedure output formatted {json} – links and all

RESTful Services, write your own code
• Modules
• Templates
• Handlers
• SourceTypes

• Base URI
• Default pagination size
• Can be protected by
common privileges
Modules

/ords/hr/untappd/beers/
/ords/hr/untappd/beers/:id
URI Templates

Handlers: Mapping Verbs to the SQL/PLSQL

• Collection Query
– Multiple records/paging
• Collection Query Item
– Single record only/no paging
• Media
– Streams the output directly
• PL/SQL
– Print HTML (HTP.P) or Code the Response
yourself (headers and body)
Source Types - Shapes Responses

RESTful Service Example #1
• aTABLE
• a RESTfulWebservice…
• …that INSERTs a record
Implementation
• Template => media/
• Handler => POST
• Source => PL/SQL

INSERT a record w/a BLOB

• ORDS defines request body & headers w/ :binds
• ORDS defines response body & headers w/ :binds
ORDS makes HTTP & SQL, easy!
INSERT INTO table (blob) VALUES (:body);
:status := 201;
:location := ‘../’ || id;

• We got the BLOB from the HTTP request via :body
• We got the other columns from HTTP request headers
• We INSERT the record
• We set HTTP LOCATION and STATUS
…in ~3 lines of PL/SQL!!!
What just happened?

RESTful Service Example #2
• aTABLE
• a RESTfulWebservice…
• …that gives list of links
Implementation
• Template => beers/:style/pics
• Handler => GET
• Source => SQL

Print a list of Rows w/LINKs to pictures

• SQL SELECT to get the data
• Predicate value pulled from URI via :type bind
• We told ORDS to generate a link with an “$alias”
What just happened?

Time to wind things down, Last Call!
• Source code, CI/CD
• Documentation
• Authorization

Backup/Source Control your REST Code
• GUI
• SQL
• CLI/Liquibase
Generated via:

Document your APIs with OpenAPI
• GUI
• REST
Generated via:

• See MY post on OAUTH2 w/ORDS
• SeeTodd’s post on OAUTH2 w/ORDS & Micronaut
SECURE Your Services

• Slides
• Blogs
• Articles
UKOUG Scene Why REST, andWhat’s in it or Me?
Oracle Magazine AUTO REST & REST Enabled SQL
Other Resources

Oracle REST Data Services: POUG Edition

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Oracle REST Data Services: POUG Edition

Similar to Oracle REST Data Services: POUG Edition (20)

More from Jeff Smith

More from Jeff Smith (7)

Recently uploaded

Recently uploaded (20)

Oracle REST Data Services: POUG Edition

Editor's Notes