Exposing the database as an APIs. Transform your data into APIs and share.

1. Vinay Kumar, ORACLE ACE
@vinaykuma201
SPOUG18-Madrid
1

2. 2
• O RACL E ACE
• Enterp ris e Arch itect
• Au th o r of B ook “ B egin n in g Oracle
Web Center portal 12c”
• O racle certified p ro fes s io n al
• B lo g ger-http ://w w w.tech artifact. com/b logs
• So ftware Co n s u ltant

3. 3
• Un der st an din g RES T
• ORDS in t rodu ct ion
• ORDS Arch itect u re
• ORDS Con n ect ion Poolin g
• Man agemen t of t h e RES T defin it ion s wit h S QL Developer an d t h e AP I
• ORDS B est P ract ices
• Web Application Arch itectu re
• Addit ion al Readin g

4. 4
Understanding REST

5. 5

6. Representational State Transfer -
6
https://en.wikipedia.org/wiki/Representaional_state_transfer

7. Why should we care for REST web services?
7

8. Understanding REST - Resources
• Resources
• HTTPverbs
• Statuscodes
• Media types
http://host/path/employeesGET
http://host/path/departments/GET
http://host/path/employees/101GET
http://host/path/departments/GET
A resource is an object with a type, associated data, relationships to other
resources, and a set of methods that operate on it.
The JSON is a representation of the resource.

9. Understanding REST - Verbs
9
• Use HTTP Verbs
• Resources
• HTTPverbs
• Statuscodes
• Media types

10. Understanding REST – Status Codes
10
• Resources
• HTTPverbs
•Status codes
• Media types
Informational
Success
Redirection
Client Error
ServerError
4xx
3xx
5xx
1xx
2xx

11. Understanding REST – Media types
11
• Resources
• HTTPverbs
• Status codes
• Media types
Payloadtype 'requested' byclient
– Via HTTPParameter"accept"
– Defines MIME types. e.g.
• application/json, application/xml, text/plain,
image/gif

12. Understanding JSON
12
JSON is a standard using
human-readable text to
transmit data objects of
attribute-value pairs. It is
typically used in machine to
machine communications and
is a contemporary
replacement for the older
XML standard.

13. ORDS - a mid-tier Java application, maps
HTTP(S) verbs (GET, POST, PUT,
DELETE, etc.) to database transactions
and returns results formatted using JSON.
13

14. Oracle Rest Data Services (ORDS)
▪ Middleware J2EE component in the applicaton/web
server (WLS, Glassfish, Tomcat)
▪ Translates URLs into a call in the database (either
select or stored procedure call)
Two major use cases
▪ Oracle Application Express (APEX)
▪ RESTful Webservices
14
Web Container
REST Data
Service
(WLS,Tomcat, Glassfish )
HTTP s
Browser / Clients
Database
JDBC connection pool

15. 15
ORDS Architecture

16. 16
HTTP/s Client Oracle Database
Oracle REST Data Service
HTTP / S
Client makes a
HTTP 'GET'
requesthttps://myhost/Customapp/sales/orders/1001
HTTP/S& URI
Module TemplateContext Root

17. 17
HTTP/s Client Oracle Database
Oracle REST Data Service
Client makes a
HTTP 'GET'
requesthttps://myhost/Customapp/sales/orders/1001
HTTP/S& URI
Module TemplateContext Root
ORDS maps to
"ORDERS" SQL
SELECT*FROMORDERS
WHEREORDERNO=:b1
HTTP / S Map and Bind

18. 18
HTTP/s Client Oracle Database
Oracle REST Data Service
Client makes a
HTTP 'GET'
requesthttps://myhost/Customapp/sales/orders/1001
HTTP/S& URI
Module TemplateContext Root
ORDSmapsto
"ORDERS"SQL
SELECT*FROM
ORDERSWHERE
ORDERNO=:b1
HTTP / S Map and BindMap andBind SQL
JDBC SQL
Call

19. 19
HTTP/s Client Oracle Database
Oracle REST Data Service
Client makes a
HTTP 'GET'
requesthttps://myhost/Customapp/sales/orders/1001
HTTP/S& URI
Module TemplateContext Root
ORDSmapsto
"ORDERS"SQL
SELECT*FROM
ORDERSWHERE
ORDERNO=:b1
HTTP / S Map and BindMap andBind SQL
ResultSet
DBreturns
result set

20. 20
HTTP/s Client Oracle Database
Oracle REST Data Service
Client makes a
HTTP 'GET'
requesthttps://myhost/Customapp/sales/orders/1001
HTTP/S& URI
Module TemplateContext Root
ORDSmapsto
"ORDERS"SQL
SELECT*FROM
ORDERSWHERE
ORDERNO=:b1
HTTP / S Map and BindMap andBind SQL
DBreturns
result set
{"orderno": 1001,
"name": "ScottKing",
"address": "500 Main street,
Innovation CA", "items": [{
"itemno": 404,"quantity":7,
"status": "in process"},
{"itemno": 303,"quantity": 32,
"status": "closed"} ]}
Transform to JSON,
CSV, Excel or Binary
ResultSetTransform

21. 21
HTTP/s Client
Oracle Database
Oracle REST Data Service
Client makes a
HTTP 'GET'
request
https://myhost/Customapp/sales/orders/1001
HTTP/S& URI
Module TemplateContext Root
ORDSmapsto
"ORDERS"SQL
SELECT*FROM
ORDERSWHERE
ORDERNO=:b1
HTTP / S Map and BindMap andBind SQL
DBreturns
result set
{"orderno": 1001,
"name": "ScottKing",
"address": "500 Main street,
Innovation CA", "items": [{
"itemno": 404,"quantity":7,
"status": "in process"},
{"itemno": 303,"quantity": 32,
"status": "closed"} ]}
JSON
Response to HTTP
request
Transform ResultSet

22. 22
HTTP/s Client
Oracle Database
Oracle REST Data Service
Client makes a
HTTP 'GET'
request ORDSmapsto
"ORDERS"SQL
HTTP / S Map and BindMap andBind SQL
DBreturns
result set
JSON Transform ResultSet
Summary: Serving JSON results from the database
 App developers call named URI over HTTP(S) to retrieve and update data
 Oracle REST Data Services (ORDS) Developer defines URI<>SQL mapping/binding
 Utilizes the data stored in standard relational tables and columns

23. 23
Client makes a
HTTP 'GET'
request
V
ORDSmapsto
"ORDERS"SQL
Map and Bind SQL
DBreturns
result set
Connection Pooling
 Each REST enabled schema grant proxy connects
 Connection open only to proxied connection
 All SQL/PLSQL execute at the schema
 Proxied connection is closed and returned to the pool.
 Utilizes the data stored in standard relational tables and columns

24. 24
Client makes a
HTTP 'GET'
request ORDSmapsto
"ORDERS"SQL
Map and Bind
DBreturns
result set
Support Multiple Oracle Data Stores
REST
Oracle REST Data Service
Oracle Relational Database
Oracle Database (document store)
Oracle NoSQL Database
Removed Oracle No SQL
support
In July 2018 – ORDS
18.2.0

25. Oracle REST Data Service
25
- Provide data access in modern application development
• Its a mid tier application.
• It is JavaScript friendly and highly scalable.
• Can declartive return result in JSON format.
• It map Http (s) request into the SQL
• Provides mapping between pl/sql to JSON.
- Services & Features
• Formally known as Oracle APEX Listener.
• Access to relational database to the http(s) with jdbc/odbc driver.
• Oracle JSON collection based schema-less access.
• It map Http (s) request into the SQL
• Provides mapping between pl/sql to JSON.
• Support HTTP Basic dynamic authentication for PL/SQL Gateway calls
• Open API (aka Swagger) support for metadata catalog

26. Oracle REST Data Service provides for REST
services
26
• Request dispatching
• JSON parsing for simple GET requests
• Generating JSON links
• Pagination control
• Authentication and Authorization support with standards
• Exception, error handling and responses (HTML)

27. Oracle REST Data Service Implementation
27
Download DeployConfigure Publish
Download latest
version of ORDS
From
edelivery.oracle.co
m
Configure ORDS
Parameter,
Database accounts
and URL mapping
Deploy ORDS.war
to the server
Use ORDS service
to publish in
Service Bus or API
management
platform

28. ORDS – URL Anatomy
28
http://localhost:8080/ords/orcl/finance/risk/emp/:empId
Base
URL
Context SchemaDatabase Module Template
Module : It contain one or more templates, with an associated path (risk/).
Template : A container for one or more handlers. The template must be unique within the module and is
associated with a specific path (emp/), which may or may not include parameters.
Resource Handler: Provides the logic required to service a particular HTTP method, for a specific Resource
Template. For example GET, POST.

29. Enable Schema & Define Module
29

30. SQL as REST
30
The DEFINE_SERVICE procedure allows you to create a new
module, template and handler in a single step. If the module
already exists, it's replaced by the new definition.
Quick BuildManual Build
=
http://localhost:8080/ords/orcl/finance/risk/emp

31. PL/SQL as REST
31
http://localhost:8080/ords/orcl/finance/risk/emp/:empId

32. p_source_type
32
• source_type_collection_feed - Executes a SQL query and transforms the result set into an ORDS Standard JSON
representation. : JSON
• source_type_collection_item - Executes a SQL query returning one row of data into a ORDS Standard JSON
representation. : JSON
• source_type_media - Executes a SQL query conforming to a specific format and turns the result set into a binary
representation with an accompanying HTTP Content-Type header identifying the Internet media type of the
representation. : Binary
• source_type_plsql - Executes an anonymous PL/SQL block and transforms IN/OUT parameters into a JSON
representation. : JSON
• source_type_query || source_type_csv_query - Executes a SQL query and transforms the result set into either an ORDS
legacy JavaScript Object Notation (JSON) or CSV representation. : JSON or CSV
• source_type_query_one_row - Executes a SQL query returning one row of data into an ORDS legacy JSON
representation. : JSON
• source_type_feed - Executes a SQL query and transforms the results into a JSON Feed representation. Each item in the
feed contains a summary of a resource and a hyperlink

33. AutoRest for Tables
33
Enable schema and table via GUI

34. AutoRest- SQL operation
34
• Select
* Method : GET
http://localhost:8080/ords/orcl/finance/risk/emp/
http://localhost:8080/ords/orcl/finance/risk/emp/122/
http://localhost:8080/ords/orcl/finance/risk/emp/?q={"sal":{"$gte":1000}}
• Insert
* Method : POST
http://localhost:8080/ords/orcl/finance/risk/emp
Payload :

35. AutoRest- SQL operation
35
• Update
* Method : PUT
http://localhost:8080/ords/orcl/finance/risk/emp/122/
• Delete
* Method : DELETE
http://localhost:8080/ords/orcl/finance/risk/emp?q={“empid”:9999}
Payload :

36. AutoRest- BatchLoad
36
• BatchLoad enables to upload batches of data using AutoREST from CSV payload.
• Post operation supported for this.
• Content type should be text/csv
• First row should contain column names.
• DateFormat can passed as query parameter.
• Bulk Upload
* Method : POST
http://localhost:8080/ords/orcl/finance/risk/emp/batchload?dateFormat="DD-MON-YYYY”
/"

37. OPEN API 2.0 (Swagger) support for API documentation
37
• ORDS exposes the metadata
of specific web services in
Open API 2.0 format.
• REST API inventory
• Test via Curl
• API Description
• Examples.
http://localhost:8080/ords/orcl/finance/metadata-catalog/
http://localhost:8080/ords/orcl/finance/open-api-catalog/ - Open API URL catalog
http://localhost:8080/ords/orcl/finance/open-api-catalog/risk/ - Output for a specific service is in the
Open API 2.0 format.

38. 38
Securing REST APIs

39. Oracle REST Data Services (ORDS) : Authentication
39
• First Party Cookie-Based Authentication
1. Only available to Author of the APIs. Create ORDS user, role and assign privileges to access the API.
2. Crendentials entered in the authentication form. ORDS generate a cookie and it is validate only by
ORDS, if the request is determined to originate from the same origin as the rest service.
• Third Party OAuth 2.0-Based Authentication
1. A third party is any party other than the author of a RESTful API.
2. Third party register with the first party, then the first party (or an end user of the first party RESTful
service) approves the third party application for limited access to the RESTful API, by issuing the third
party application a short-lived access token.

40. Oracle REST Data Services (ORDS) : Authentication
40
Basic Auth OAuth
ORDS Role
Privileges
Users Clients
URL Mapping
Create Users Register Clients & Generate
client Id and client secret
Access APIs
via passing
crendentials
(User name
and password)
Pass client id,
client secret &
token to
access APIs

41. Oracle REST Data Services (ORDS) : Authentication
41
• Create a ORDS role and associated
privileges.
• Map the privileges to the web
services.
1
2
3

42. Oracle REST Data Services (ORDS) : Authentication - OAUTH
42
1. Client Credentials
'Two-legged' process. OAuth involves two parties, the party calling the RESTful API (the third party application), and the
party providing the RESTful API. Two legged flows are typically used in server to server interactions where the calling
server can securely store the credentials required to access the service. In OAuth 2.0 this flow is called the client
credentials flow. It is most typically used in business to business scenarios.
2. Authorization Code
'Three-legged' Process .OAuth involves three parties, the party calling the RESTful API, the party providing the RESTful API,
and an end-user party, who owns/manages the data that the RESTful API provides access to. Three legged flows are used in
client to server interactions where an end-user must approve access to the RESTful API. In OAuth 2.0 the authorization code
flow and the implicit flow are three legged flows. These flows are typically used in business to consumer scenarios.
3. Implict
'Two-legged' process. The user accesses a URL in a browser, which prompts for credentials. Once authenticated, the
browser is redirected to a specified page with an access token as one of the parameters in the URL. That access token is
used to authenticate calls to protected resources.

43. ORDS : Authentication - OAuth 2 : Client Credentials
43

44. ORDS : Authentication - OAuth 2 : Client Credentials
44
1
Client registered in ORDS and client id and
client_secret can be generated.
2
Associate the client with the role

45. Application Architecture
45
User Interface (JET App)
ESB (SB, BPEL)
DataBase
ORDS
Partners/
Externals
MobileCloud Apps
API Gateway
BPM
Webserver/ App Server
SOAPREST
REST

46. ORDS Best Practices
46
• Build Url Carefully
https://example.com/<warfile>/<schemaname>/<module>/<service>
1. Don’t put 'ords' in your URL. Either rename ORDS.war to something else e.g. API.war or add a
rule in the web server.
2. While enabling database schema, think do you want to put schema name in the REST
endpoints.
3. If API versioning part of the APIs strategy, then use module as the version.
• Control/limit Business Logic in ORDS handler
1. Move logic into PL/SQL packages.
1. This includes getting http headers (think owa_util) and writing the response (think htp.p). This
not only organizes your code better and makes it easier to reuse but it also makes it easier to
deploy changes.

47. ORDS Best Practices - continued
47
• Authentication
1. Think about authentication mechanism and where you want to have logic.
2. Using OAUTH option depending on your requirements
OAuth 2 : Client Credentials -
OAuth 2 : Authorization Code
OAuth 2 : Implicit
• Error Message & Custom Error Pages
1. Build clear error message.
• Authorization
• Follow REST Principles

48. Additional Reading
48
• The REST API Design Handbook by George Reese & Christian Reilly
• SOA with REST by Thomas Erl
• https://docs.oracle.com/en/database/oracle/oracle-rest-data-services/18.2/index.html
• https://oracle-base.com/articles/misc/articles-misc#ords
• https://stormpath.com/blog/secure-your-rest-api-right-way

49. 49

50. Neal Creative | click & Learn moreNeal Creative ©
THANK YOU
Vinay Kumar
@Vinaykuma201
mail2vinayku@gmail.com
www.techartifact.com/blogs