REST APIs and

the Oracle Converged Database

Jeff Smith
Distinguished Product Manager
Jeff.D.Smith@oracle.com
Tweets: @thatjeffsmith
Blogs: https://www.thatjeffsmith.com
Format
• 75 minutes lecture
• Hands-On Lab introduction
• Questions? Zoom Q&A
• Recorded? YES
• SLIDES? YES
Agenda
• What makes an API, RESTful?
• Why should we care?
• How it works/Architecture
• examples
• Oracle Converged Database
• Database Management APIs
 REST
• Representational Stateless Transfer
• Architectural Style for networked applications
• Communicated via HTTPS, but
• HTTPS <> REST
 RESTful APIs
• Predictable, familiar for developers
• Model nouns not verbs
• Proper Responses
• LINKS
RESTful Ugh!
RESTful Ugh!
POST things/ GET delete_things/
Request: POST things/ Request: POST things/
GET things/:id
Response: 201 CreatedPOST things/new_thing
Response: 200 OK
Location /things/123
 Cool, but why do I care?
• Everything is HTTPS/JSON
• Developers will go around you
• Database needs CI/CD, automation, mon…
• Microservices!
HTTPS > SQL > HTTPS
SELECT *
FROM EMPS
GET https://host/ords/hr/beers/1
WHERE ID = 1

HTTP URI
Request Marshalls to Database SQL & PLSQL

HTTP Response Transforms to JSON SQL Result Set / Standard OUT

Oracle REST Data Services

HTTP/1.1 200 OK

{json} { "id": 1,
"name": "Jeff",
"job": "PM",
"salary": 100 }
 ORDS Architecture
Webserver layout
HTTP(s) Request
• Results

• Java Servlet Apache

/ords/…
Static Files
-HTML, CSS, JS
JSON

Tomcat/WLS or
Binary
/db1/hr/emp/
• HTML
…
ORDS

• Standalone Java app Tomcat, WLS

JDBC JDBC JDBC
pool1 pool2 pool3
DatabaseS and HA Tips
• Each database gets a connection pool
• CDBs, PDBs, or single instances
• Each database gets a mapping pattern
ords/
ords/db2/…
ords/db3/…

TIP 1: 3 ORDS front-ended with a load balancer

TIP 2: Data Guard/Scan Listener for your DB, ORDS will immediately pick up
 Connection Pools
• JDBC Conn Pools
• Default Size: 10
• 1st pool => ords/
• ORDS_PUBLIC_USER ..

Tip 1 : Customers MUST tune connection pools

Tip 2: Bigger Pools <> FASTER!

Whitepaper: Real World Perf Sizing Guide

Video: Office Hours Session
 Configuration
• CLI for configuration changes or..
• Edit pool XML and/or Standalone properties files
Watch Later…
 ORDS & Your Database
• ORDS_PUBLIC_USER
• ORDS_METADATA
• ORDS.ENABLE_SCHEMA()
• APIs published to SCHEMA
• APIs exec as USER

Modeling ORDS_METADATA with Database Actions (ORDS)

 Where APIs come from
1. REST Enable Schema
2. REST Enable Object OR
2. Publish a REST Module
REST Enabling
BEGIN
ORDS.ENABLE_SCHEMA(
p_enabled => TRUE,
p_schema => 'HR',
p_url_mapping_type => 'BASE_PATH',
p_url_mapping_pattern => 'peeps',
p_auto_rest_auth => TRUE);
commit;
END;
Step 1…you’re not done
Built-in Dev Tools
No or Low Code
AUTOREST RESTful Service
• CRUD APIs, no code • Your code -
• Maintained by ORCL • Inputs, outputs, error handling,
• Feature rich response codes, formatting
• Optimized • Full access to SQL/PLSQL
• Easily exported, source controlled
• Transparent
AUTOREST: TABLE
CRUD APIs, for free
POST => INSERT
PUT => UPDATE
DELETE => DELETE
POST…BatchLoad
Batchloading 10M rows

Oracle Confidential – Internal/Restricted/Highly Restricted

GET /?q=…
Like coding? Modules!
Techniques/tricks
RESTful Service
• Your code -
• Inputs, outputs, error handling,
response codes, formatting
• Full access to SQL/PLSQL
• Easily exported, source controlled
• Transparent
REST Module: 2+Tables
SQL: JOIN
Binds in the URI
SQL: CURSOR
SQL & Paging
ALT: AUTOREST a VIEW
REST is LINK DRIVEN

FAIL
GENERATING LINKS
Building your Templates
Avoid dead-ends
POST vs GET
 POST/PUT Tips
• Request Mime Type: Application/JSON
• :x – looks for {"x" :…}
• Parameters
• :bind is the VAR in the blog, name is the HEADER label
• Use to work with REQUEST or RESPONSE elements of your API
 PL/SQL
1. ORDS Enable PL/SQL (package, proc, func)
2. OR Publish a REST Module
AUTO RESTful Service
• RPC for PL/SQL program • Your code -
• Input params in req body • Inputs, outputs, error handling, response
• OUT/RETURNs codes, formatting
transformed and returned • Print HTML, return JSON, download
as JSON response files…
 PL/SQL & REFCURSORs
1. SELECT – func with OUT sys_refcursor
2. ANON Block
3. Call SP, send OUT to a RESULTSET OUT PARAM
4. AUTO
AUTO PL/SQL REFCUR
ANON Block REFCUR
PL/SQL Download File
CREATE OR REPLACE PROCEDURE download_file ( media_id NUMBER ) AS
vMIMETYPE VARCHAR2(256);
vLENGTH NUMBER;
vFILENAME VARCHAR2(2000);
vBLOB BLOB;
BEGIN
SELECT file_name, content_type, content INTO vFILENAME, vMIMETYPE, VBLOB
FROM media
WHERE id = media_id;
vLENGTH := DBMS_LOB.GETLENGTH(vBLOB);
owa_util.mime_header(NVL(vMIMETYPE, 'application/octet'), FALSE);
htp.p('Content-length: ' || vLENGTH);
htp.p('Content-Disposition: attachment; filename=' || SUBSTR(vFILENAME, INSTR(vFILENAME, '/') + 1) || ‘’);
owa_util.http_header_close;
wpg_docload.download_file(vBLOB);
END download_file;
/
Uploading Files - BLOBS
Converged Database
• One DB engine – ALL data & workloads
• Support for Microservices, Events, REST, SaaS…
• Accessed/Managed with SQL * PL/SQL
Read more on Converged Databases with Maria Colgan
JSON Documents

POST HTTPS://.../ords/hr/soda/latest/thatjeffsmith/ GET HTTPS://.../ords/hr/soda/latest/thatjeffsmith/123456...

Spatial, GeoJSON
XML
Analytics & ML
Secure APIS
• Requests must be authenticated & authorized!
• APIs are protected via required roles
• Authentication can be managed by Web Server OR
Use ORDS BASIC Auth
Database Auth
Built-in OAuth2 Workflow
Secure APIS
Security

OAuth2
DBA. Me. Want. Stuff!
• Provide access, easily to your DBs
• Automation
• Monitoring
DB-API: 500+ Endpoints
Performance Monitoring PDB Lifecyle General

What isn’t running well? Problematic Activity Multitenant Management Data Dictionary Reports
• ASH • Sessions • Create • tables/,
• AWR • Locks • Clone tables/{table}
• RTSM • Waits • Change State • indexes/…
• Top SQL • Alert Log • Drop Database Operations
• Reports • DBCA
• Data Pump
DB-API: Turn it on
<entry key="database.api.enabled">true</entry>
DB-API: Docs

Oracle Docs OpenAPI.JSON Endpoint

Service Catalog
 Data Pump via HTTPS
POST BODY Response
{
"datapump_dir":"DATA_PUMP_DIR",
"filter" :"HOCKEY_STATS",
"job_mode" :"TABLE",
"threads" :2
}
Web Tooling for Users
Homework
Extra Credit!
Resources
• SlideShare/SpeakerDeck
• Blogs (thatjeffsmith.com)
• GitHub
• Articles
UKOUG Scene Why REST, and What’s in it or Me?
Oracle Mag AUTO REST & REST Enabled SQL

• And don’t forget Oracle-Base!