Oracle Office Hours - Exposing REST services with APEX and ORDS

Copyright © 2019, Oracle and/or its affiliates. All rights reserved.
Exposing RESTful Services
A soup-to-nuts walkthrough of building, exposing and securing web services
using Oracle APEX and ORDS

Safe Harbor
The following is intended to outline Oracle’s general product direction.
It is intended for informational purposes only, and may not be
incorporated into any contract. It is not a commitment to deliver any
material, code, or functionality, and should not be relied upon in
making purchasing decisions.
The development, release, and timing of any features and
functionality described for Oracle’s products remains at the sole
discretion of Oracle.
2

Doug Gault
3
• Started Working with Oracle in 1988 (V 5.1b)
• 30+ years of consulting experience on Oracle
• Joined Oracle in 2016
• Based in FortWorth,Texas
Twitter: @DougAGault
Email : douglas.gault@oracle.com
Blog: douggault.com
Consulting Member of Technical Staff
Doug Gault
4
• Started Working with Oracle in 1988 (V 5.1b)
• 30+ years of consulting experience on Oracle
• Joined Oracle in 2016
• Based in Fort Worth, Texas
Twitter: @DougAGault
Email : douglas.gault@oracle.com
Blog: douggault.com
Consulting Member of Technical Staff

Today’sAgenda
• A very brief overview of REST
• A very brief history of REST in APEX and ORDS
• A very high level overview of what ORDs provides
• LETS JUST DOTHISTHING!
• Create RESTful services on EMP / DEPT
• Secure those services
• Consume those services using PL/SQL
• Hopefully there’ll be time for questions…
• I’ll provide lots of links where you can get more information
4

What is REST
A very brief overview
5
{ }

REST in a nutshell
• Representational State Transfer
• An architecture that provides interoperability between two computer systems
• Uses HTTP(s) protocol as a transport protocol
• Content usually represented via JSON or XML
• The great thing about REST is that the two participants in the
communication can be completely different in terms of
• Language (JAVA,.NET, PHP, etc.)
• Database (Oracle, Microsoft, MongoDB, Hadoop, Couchbase, etc.)
• Arcitecture (On Premises, Cloud, Mixed)
• The Main tenant being, the service being called must be reachable by the
caller
6

Copyright © 2019, Oracle and/or its affiliates. All rights reserved. 7
REST allows computer to talk
Request
Response
Caller Provider

Communication over HTTP
• REST communicates over HTTP, therefore uses standard HTTP
methods
• GET – Lookups or request for data accessible via the service (SELECT)
• PUT – Mutation of data controlled by the service (UPDATE)
• POST – Creation of new data (INSERT)
• DELETE – Deletion of data controlled by the service (DELETE)
• For more in-depth information on REST (and there is a lot!), a good
place to start would be https://restfulapi.net/
8
METHOD SQL EQUIVALENT

REST, APEX and ORDS
A very brief history
9

APEX based REST services
• First introduced in APEX 4.2
• Stores RESTful definitions in APEX
Repository
• Remained “TheAPEXWay” through
version 5.1
ORDS based REST services
• First Introduced in ORDS 2.0
• Oringinally stored definitions in APEX
• V3.0+ Introduced ORDS_METADATA
Repository
10
United we stand …
• APEX Based RESTful services were deprecated in APEX 18.1
• ORDS_METADATA is the single repository of record moving forward
• Migrate all APEX Based services to ORDS Based Restful services
• Develop all new services using ORDS
• In the future, APEX RESTful service console will likely be removed
• Gives users a unified view no matter what tool they use

Oracle Rest Data Services
• Fully supported feature of the Oracle Database
• If you have a license for the database, it covers ORDS
• Technically ORDS is all that is required to expose REST services
• Provides all the requirements to build, expose and secure
• ORDS PL/SQL API’s to manage
• REST Enablement of a given schema
• Definition of REST Service Modules and Handlers
• Definition of Security Privileges and Roles
• AutoREST Enablement of Database Objects
• ORDS_METADATA Repository Views provide
• Full access to all services and security definitions for the current schema
11

Application Express
• Fully supported feature of the Oracle Database
• If you have a license for the database, it covers APEX
• From 18.1+ APEX now provides a GUI on top of the ORDS APIs
• Users can no longer create APEX Based RESTful Services
• Instead, use the ORDS RESTful Workshop to
• Create and manage
• RESTful Service definitions
• Privileges
• Roles
• Very similar to the interface provided by SQL Developer
12

Becoming RESTful
A very high level overview of the ORDS APIs
13

Exposing data through REST
• ORDS Provides two different ways to expose data via REST
• AutoREST Enablement
• Concept of making database resources available via ORDS with Zero Code
• Can expose Tables, Views, Packages, Procedures, and Functions
• You sacrifice flexibility and customizability for ease of creation
• No customization of included columns or data format
• No way to introduce extra validation or logic
• Manual REST Service Creation
• Requires you to specify the SQL or PL/SQL to support the required actions
• More effort but definitely more flexibility
• Can customize columns, Join across multiple tables, etc.
• Validate incoming data using PL/SQL
• Include complex logic to decide what actions to take (if any)
• In both cases the underlying schema must first be ORDS Enabled
14

REST Service Components
• Understanding ORDS URITerminology
• ORDS Alias – Alias for the ORDS engine (Defined at the web server level)
• Schema Alias – Defines the path used to reach the ORDS Enabled schema
• Module – Defines the BASE_PATH for a group of related services
• Template – Defines the path that is used to access a specific resource
• Handler – Defines the code executed for each handler type (GET, POST, PUT, DELETE)
15
http://server.com/ords/mySchema/hr/employees/:id
|________________|____|________|_|_________|____|
| | | | | |
| | | | | - Bind Variable
| | | | |
| | | | - URI Template
| | | |
| | | - Module Base Path
| | |
| | - Schema Alias
| |
| - ORDS Alias
|
- Server URL

REST URLs to Note
• Available
• If Auto REST Privilege is not required
• If your user is assigned the required privilege
• Information about all services available within the schema
• http://<server>/ords/<schema_alias>/metadata-catalog/
• http://<server>/ords/<schema_alias>/open-api-catalog/
• Information about a specific service within the schema
• http://<server>/ords/<schema_alias>/metadata-catalog/<service_name>
• http://<server>/ords/<schema_alias>/open-api-catalog/<service_name>
16
Open-API style should be preferred as they provide more information and
can be used to create Swagger style documentation.

The ORDSAPI
• ords.enable_schema
• ords.drop_rest_for_schema
• ords.set_url_mappings
• ords.enable_object
• ords.define_service
• ords.define_module
• ords.publish_module
• ords.rename_module
• ords.set_module_origins_allowed
• ords.delete_module
• ords.define_template
• ords.define_handler
• ords.define_parameter
• ords.create_role
• ords.rename_role
• ords.delete_role
• ords.define_privilege
• ords.rename_privilege
• ords.delete_privilege
17

ORDS Enabling Schemas
18

Enable Schema using APIs
ORDS.ENABLE_SCHEMA(
p_enabled => TRUE, -- Enables/Disables the schema 1
p_schema => 'DOUG', -- Schema to Enable 2
p_url_mapping_type => 'BASE_PATH', -- URL Mapping Type
p_url_mapping_pattern => 'douglas', -- Mapping Pattern 3
p_auto_rest_auth => FALSE); -- Require Auth for metadata 4
• Makes ORDS aware that
• the schema exists
• it may have zero to many resources exposed
• Only needs to be done once for the schema
1 – Disabling the schema only disabled external access to it’s resources. It does not de-register from ORDS or affect your REST service definitions.
2 – Only database users with DBA privileges may enable or disable schemas other then their own
3 – For Security purposes, the mapping pattern should be different from the underlying schema name
4 – This does not mean Authorization is required to access the resource, only to access the metadata for the resource
19

Enable Schema using APEX
20
p_endabled
p_schema
p_url_mapping_pattern
p_auto_rest_auth
ORDS.ENABLE_SCHEMA

Enable Schema
Demo
21

AutoREST
220

AutoREST using APIs
ORDS.ENABLE_OBJECT(
p_enabled => TRUE, -- Is AutoREST Access enabled
p_schema => 'DOUG', -- Schema owning the object1
p_object => 'DEPT', -- Object Name
p_object_type => 'TABLE', -- Object Type2
p_object_alias => 'dept', -- Object Alias3
p_auto_rest_auth => FALSE); -- Role required for access4
• Makes Object available via REST
1 – Only database users with DBA privileges may enable or disable schemas other then their own
2 – Object types can be TABLE, VIEW, PACKAGE, PROCEDURE, FUNCTION
3 - For Security purposes, the object alias should be different from the underlying object name
4 – Indicates whether external users trying to access the REST enabled object are required to be assigned the related role. oracle.dbtools.role.autorest.[SCHEMA].[OBJECT]
23

AutoREST using APEX
24
p_schemap_object_aliasp_auto_rest_auth
p_enabled
p_object_type
p_object_name
ORDS.ENABLE_OBJECT

AutoREST Primer
• What AutoREST gives you depends on the object type
• Tables provide full REST compliment out of the box
• GET (SELECT)
• POST (INSERT)
• PUT (UPDATE)
• DELETE (DELETE)
• Views provide only row retrieval
• GET (SELECT)
• Procedures, Functions and Packages provide execution
• POST (EXEC)
25

AutoREST Demo
26

Manual REST Service Creation
270

Service Creation Example using APIs
28
BEGIN
ORDS.DEFINE_MODULE(
p_module_name => 'hr.example.service',
p_base_path => '/hr/',
p_items_per_page => 25,
p_status => 'PUBLISHED',
p_comments => NULL);
ORDS.DEFINE_TEMPLATE(
p_pattern => 'employees/',
p_priority => 0,
p_etag_type => 'HASH',
p_etag_query => NULL,
p_comments => NULL);
ORDS.DEFINE_HANDLER(
p_pattern => 'employees/',
p_method => 'GET',
p_source_type => 'json/collection',
p_mimes_allowed => '',
p_comments => NULL,
p_source => 'select * from emp');
COMMIT;
END;
BEGIN
ORDS.DEFINE_SERVICE(
p_base_path => '/hr/employees/’
p_pattern => '.'
p_method => 'GET'
p_items_per_page => 25,
p_status => 'PUBLISHED’,
p_etag_type => 'HASH'
p_source => 'select * from emp');
COMMIT;
END;

Service Creation Example using APEX
29
p_module_name
p_base_path
p_status
p_items_per_page
p_comments
ORDS.DEFINE_MODULE

30
p_module_name
p_pattern
p_priority
p_etag_type
p_comments
ORDS.DEFINE_TEMPLATE

31
p_module_name
p_pattern
p_method
p_source_type
p_items_per_page
p_comments
p_source
ORDS.DEFINE_HANDLER

32

GET Response
33

What about Insert, Update & Delete?
• For each action, you would need to create a new handler
• INSERT – Create a POST handler with INSERT logic
• UPDATE – Create a PUT handler with UPDATE logic
• DELETE – Create a DELETE handler with DELETE logic
• You may be tempted to fall back to AutoREST, but remember
• You can not control the columns returned
• You can not control the format of the JSON
• You can not inject any logic around Insert, Updates, or Deletes
• What you gain in ease of creation, you give up in control
34

Manual REST
Demo
35

More Info on Creating REST Services
• Here are some really good resource for diving deeper into developing
ORDS based REST Services
• Jeff Smith’s Blog (Click ‘Rest Data Services’ link)
• https://www.thatjeffsmith.com/oracle-rest-data-services-ords/
• https://github.com/oracle/oracle-db-tools/tree/master/ords/
• Oracle Learning Library (search for ‘ORDS REST’)
• https://apexapps.oracle.com/pls/apex/f?p=44785:1
• Tim Hall’s ORACLE-BASE blog (search for ‘ORDS REST’)
• https://oracle-base.com/
• The Documentation (19.1 Quick Start Guide)
• Walkthrough of creating and securing a service.
• The Google (Search for ‘Creating ORDS REST Services’)
• 926,000 results
36

Securing REST Services
Here’s where it gets a wee bit dicey…
37

REST Authentication
• The Moving Parts
• Module – The REST Service itself
• Role – ORDS Role
• Think of it like a database role. By itself, it’s kind of meaningless
• Can be associated with Privileges and Clients
• Privilege – Links Role(s) and Module(s) to define security
• Thing of it like a Database Privilege
• Used to limit access to specific modules, or by URL Patterns
• Client – The consumers of the protected modules
• All pieces work together to provide security
NOTE: A Module can only be associated with a single privilege
38

REST Authentication
• Authentication comes in multiple Flavors
• FIRST PARTY
• Also known as BASIC AUTH
• Uses a Username/Password combo to protect a service
• ORDS 18.1+ Supports Basic Auth using
• Database users
• APEX Workspace users
• OAuth2
• Two-legged (Client Credentials Flow)
• Involves only the Provider and the Consumer of the service
• Owner of the service creates a “Client”, assigns it privileges and provides details to the consumer
• Three-legged (Third Party)
• Involves Provider, Consumer and “Controller”
• Usually involves manual intervention to approve usage
• Not very commonly used due to need for manual interaction
39

Basic Auth – DatabaseCredentials
• Using ORDS 18.1+
• Requires a change to the defaults.xml file of ORDS
• ADD
• <entry key="jdbc.auth.enabled">true</entry>
• REMOVE
• <entry key="security.requestValidationFunction">wwv_flow_epg_include_modules.authorize</entry>
• Not necessarily the advisable for security reasons
• Better to use OAuth2
40

Basic Auth – DatabaseCredentials
1. Create Database User ZEUS
• CREATE USER ZEUS IDENTIFIED BY ZEUS;
• GRANT CREATE SESSION TO ZEUS;
2. Create a Database Role
• CREATE ROLE ORDS_REST_ROLE_1
3. Grant Role to a user
• GRANT REST_ROLE_1 TO ZEUS;
4. Create ORDS Role that matches the DB Role exactly
5. Protect a service using that ORDS role
6. User ZEUS will be able to use the protected service
41

Basic Auth – APEX Credentials
• Using ORDS 18.1+
• No specific changes required at ORDS level
1. Create APEX User (can be unprivileged end user)
• Milo:Milo
2. Create APEX User Group
• APEX_REST_GROUP_1
3. AssignAPEX User to APEX Group
• Milo => APEX_REST_GROUP_1
4. Create ORDS Role that matches the APEX Group name exactly
5. Protect a service using that ORDS role
• User Milo will be able to use the protected service
42

Basic AuthWarning!!!
• When using an ORDS ROLE and BASIC AUTH, beware when naming
your ROLES
• If an ORDS role matches a DB ROLE or APEX USER GROUP
• Any users assigned that role would have access to the REST service
• For DB Credentials, this is only true when DB AUTH is enabled in ORDS
• For APEX Users, this is ALWAYS true
• This is why it’s unadvisable to use BASIC Auth when you need tight
security.
• It’s would be easy to accidently let someone in without knowing
43

More information on Basic Auth
• Tim St. Hilaire has done a great blog post and video on this
• https://wphilltech.com/apex-and-rest-authentication-basic/
44

BASIC Auth
APEX Users
45

OAuth2 –Two Legged Auth
• As the name suggests, there are two sides to this story
46
Server Side
Define the Module
Create a Role
Create a Privilege
Create Client Credentials
Link Module, Role, Privilege & Client
Client Side
Authenticate as Client
Validate/Retrieve Token
Use token to access resource

The ORDS OAUTH API andViews
• oauth.create_client
• oauth.rename_client
• oauth.update_client
• oauth.delete_client
• oauth.grant_client_role
• oauth.revoke_client_role
• USER_ORDS_CLIENTS
• USER_ORDS_CLIENT_ROLES
• USER_ORDS_CLIENT_PRIVILEGES
47
Currently no UI (not even in SQL-Developer)

Creating a Client
• To create a client we use the API
• We must associate a Privilege to our client on creation
• We can use the same Privilege we created before (HRPriv)
48
BEGIN
oauth.create_client (
p_name => 'MyClient',
p_grant_type => 'client_credentials',
p_description => 'Privileged user for employees service',
p_support_email => 'douglas.gault@oracle.com',
p_privilege_names => 'HRPriv'
);
COMMIT;
END;

Creating a Client
• We also need to associate a role with the client we just created
• Again, we’ll use the role we already created (APEX_REST_1)
49
BEGIN
oauth.grant_client_role(
p_client_name => 'MyClient',
p_role_name => 'APEX_REST_1'
);
COMMIT;
END;

Querying Client Details
50
select name,
auth_flow,
response_type,
client_id,
client_secret
from user_ords_clients
NAME AUTH_FLOW RESPONSE_TYPE CLIENT_ID CLIENT_SECRET
MyClient CLIENT_CRED TOKEN g98fjRb3w41K96L9IPsamg.. aUttds_IfDfKky-Wadpprg..

OAuth2 –Two Legged Auth
• As the name suggests, there are two sides to this story
51
Server Side
Define the Module
Create a Role
Create a Privilege
Create Client Credentials
Link Module, Role, Privilege & Client
Client Side
Authenticate as Client
Validate/Retrieve Token
Use token to access resource

Steps to access using Client Credentials
1. RetrieveToken using Client ID and Client Secret
• Token URL is
http(s)://<server>/<ords_alias>/<schema_alias>/oauth/token
52
curl -i --user g98fjRb3w41K96L9IPsamg..:aUttds_IfDfKky-Wadpprg..
--data "grant_type=client_credentials”
http://localhost:8080/ords/douglas/oauth/token
HTTP/1.1 200 OK
Content-Type: application/json
{"access_token":"bvlPtFDgXEk-uJ8_5rYQLw..",
"token_type":"bearer",
"expires_in":36000}

Steps to access using Client Credentials
2. Access REST Service usingToken
53
curl -i –H "Authorization: Bearer bvlPtFDgXEk-uJ8_5rYQLw..”
http://localhost:8080/ords/douglas/hr/employees/
{"items":[{"empno":7369,"ename":"SMITH","job":"CLERK","mgr":7902,"hiredate":"1980-12-
17T06:00:00Z","sal":800,"comm":null,"deptno":20},{"empno":7499,"ename":"ALLEN","job":"SALESMAN","mgr":7698,"hiredate":"1981-02-
20T06:00:00Z","sal":1600,"comm":300,"deptno":30},{"empno":7521,"ename":"WARD","job":"SALESMAN","mgr":7698,"hiredate":"1981-02-
22T06:00:00Z","sal":1250,"comm":500,"deptno":30},{"empno":7566,"ename":"JONES","job":"MANAGER","mgr":7839,"hiredate":"1981-04-
02T06:00:00Z","sal":2975,"comm":null,"deptno":20},{"empno":7654,"ename":"MARTIN","job":"SALESMAN","mgr":7698,"hiredate":"1981-09-
28T05:00:00Z","sal":1250,"comm":1400,"deptno":30},{"empno":7698,"ename":"BLAKE","job":"MANAGER","mgr":7839,"hiredate":"1981-05-
01T05:00:00Z","sal":2850,"comm":null,"deptno":30},{"empno":7782,"ename":"CLARK","job":"MANAGER","mgr":7839,"hiredate":"1981-06-
09T05:00:00Z","sal":2450,"comm":null,"deptno":10},{"empno":7788,"ename":"SCOTT","job":"ANALYST","mgr":7566,"hiredate":"1982-12-
09T06:00:00Z","sal":3000,"comm":null,"deptno":20},{"empno":7839,"ename":"KING","job":"PRESIDENT","mgr":null,"hiredate":"1981-11-
17T06:00:00Z","sal":5000,"comm":null,"deptno":10},{"empno":7844,"ename":"TURNER","job":"SALESMAN","mgr":7698,"hiredate":"1981-09-
08T05:00:00Z","sal":1500,"comm":0,"deptno":30},{"empno":7876,"ename":"ADAMS","job":"CLERK","mgr":7788,"hiredate":"1983-01-
12T06:00:00Z","sal":1100,"comm":null,"deptno":20},{"empno":7900,"ename":"JAMES","job":"CLERK","mgr":7698,"hiredate":"1981-12-
03T06:00:00Z","sal":950,"comm":null,"deptno":30},{"empno":7902,"ename":"FORD","job":"ANALYST","mgr":7566,"hiredate":"1981-12-
03T06:00:00Z","sal":3000,"comm":null,"deptno":20},{"empno":7934,"ename":"MILLER","job":"CLERK","mgr":7782,"hiredate":"1982-01-
23T06:00:00Z","sal":1300,"comm":null,"deptno":10}],"hasMore":false,"limit":25,"offset":0,"count":14,"links":[{"rel":"self","href":"ht
tp://localhost:8080/ords/douglas/hr/employees/"},{"rel":"edit","href":"http://localhost:8080/ords/douglas/hr/employees/"},{"rel":"des
cribedby","href":"http://localhost:8080/ords/douglas/metadata-
catalog/hr/employees/"},{"rel":"first","href":"http://localhost:8080/ords/douglas/hr/employees/"}]}

OAuth2
54

Consuming REST
using PL/SQL
You can teach an old dog new tricks!
55

Prerequisites
• Calling Database User must have correct ACL’s in place
• If you’re using APEX_WEB_SERVICE then the ACL must be in place for APEX
• Using HTTPS
• Must set up Oracle Wallet to hold the trusted Certificates
• Will likely need a DBA’s help here
• Not a straightforward process
56

PL/SQL Using BASIC AUTH
57
create or replace PROCEDURE REST_BASIC_AUTH AS
l_return clob;
BEGIN
-- Simple call using APEX_WEB_SERVICE
l_return := apex_web_service.make_rest_request(
p_url => 'http://localhost:8080/ords/douglas/hr/employees/'
p_http_method => 'GET',
p_scheme => 'Basic',
p_username => 'milo',
p_password => 'milo');
dbms_output.put_line(l_return);
END REST_BASIC_AUTH;

PL/SQL Using OAuth2
58
CREATE OR REPLACE PROCEDURE REST_OAUTH2 AS
l_return clob;
BEGIN
-- Authenticate
apex_web_service.oauth_authenticate (
p_token_url => 'http://localhost:8080/ords/douglas/oauth/token',
p_client_id => 'g98fjRb3w41K96L9IPsamg.. ',
p_client_secret => 'aUttds_IfDfKky-Wadpprg..');
-- Set up the headers to use the token
apex_web_service.g_request_headers(1).name := 'Authorization';
apex_web_service.g_request_headers(1).value := 'Bearer '||
apex_web_service.g_oauth_token.token;
-- Call the web service
l_return :=apex_web_service.make_rest_request(
p_url => 'http://localhost:8080/ords/douglas/hr/employees/',
p_http_method => 'GET');
--
dbms_output.put_line(l_return);
END REST_OAUTH2;

Retrieve using
PL/SQL
59

Oracle Office Hours - Exposing REST services with APEX and ORDS

Oracle Office Hours - Exposing REST services with APEX and ORDS

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Oracle Office Hours - Exposing REST services with APEX and ORDS

Similar to Oracle Office Hours - Exposing REST services with APEX and ORDS (20)

Recently uploaded

Recently uploaded (20)

Oracle Office Hours - Exposing REST services with APEX and ORDS

Editor's Notes