Implementing RESTful Web Services with Oracle Application Express

makeshiftklipInternet and Web Development

Oct 31, 2013 (3 years and 9 months ago)

127 views

1

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

2

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Implementing
RESTful

Web
Services with

Oracle Application Express

3

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

The following is intended to outline Oracle’s general
product direction. It is intended for information
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 or functionality described for Oracle’s
products remains at the sole discretion of Oracle.

4

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Agenda


Introduction to REST


REST Modeling


APEX
RESTful

Services Use Cases


APEX
RESTful

Services Architecture


Walk through complete sample including:


Resources using GET, PUT, POST, DELETE methods


Testing, debugging


Authentication


Q & A


5

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Introduction to REST


6

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Examples


Public services with
RESTful

APIs:


Twitter, Netflix,
Dropbox
,
Flickr
, Amazon S3, ...


Products or tools with
RESTful

APIs


Glassfish Application Server Admin, Selenium
WebDriver
, ...


RESTful

Frameworks


Jersey (JAX
-
RS),
Restlet
,
Restify
, APEX
RESTful

Services, ...


7

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

What is REST?


REST stands for Representational State Transfer.

(Sometimes written
ReST
)


It describes an architecture for distributed information systems


First described in the 2000 doctoral dissertation

“Architectural Styles and the Design of Network
-
based Software
Architectures” by Roy Fielding.


It’s a description of how the Web works and why it works well



8

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

So what is REST?


Client


Server


request response


Stateless


Caching


Layered


Code on demand (optional)


Uniform interface:

Request response style operations on named resources
through self descriptive representations where state changes
are via hyperlinks



9

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Motivation and Characteristics


Hyper media


Optimized for large grained static (cacheable) messages


Internet scale


not just size or geography


many independent organizations


Extensibility, flexibility, responsiveness


“hypermedia as the engine of application state”


Application state is 100% on the client


The state or resources is persisted behind the servers


10

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Benefits


Scalability


stateless, caching, gateways. Have more clients just add
more servers or intermediaries.


Performance


caching, compression, incremental rendering, pre
-
fetch


Simple client


uniform interface means single client implementation
can access any resource


Simple server


no extra layers and no state


No need for resource discovery due to hyperlinks


Reliability


redundancy


multiple servers


Separation of concerns and uniform interface allows clients and
servers to change and be developed independently



11

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Uniform Interface

The REST Triangle:


Resources


Methods


Representations


Resources

Nouns
Unconstrained

Methods

Verbs
Constrained

Representations

Hyper Linked
Constrained

12

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Uniform Interfaces
-

Resources


Key abstract concept


Identified by a URI


Distinct from underlying storage


Semantics fixed


Value may change over time


Can have multiple URIs


Can have multiple representations


Examples:


http://example.org/NewOrleans/traffic/10


http://example.org/traffic/NewOrleans/I10


http://foo.com/store/orders


Resources

Nouns
Unconstrained

Methods

Verbs
Constrained

Representations

Hyper Linked
Constrained

13

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

User Interface
-

Methods


Constrained set


GET safe


PUT idempotent


DELETE idempotent


POST not safe or idempotent


Apply to the resource


GET retrieve


PUT update (or create)


DELETE
delete


POST create sub resource


Response

codes 1xx, 2xx, 3xx,
4xx, 5xx



Resources

Nouns
Unconstrained

Methods

Verbs
Constrained

Representations

Hyper Linked
Constrained

14

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

User Interface
-

Representations


Not the actual resource


Constrained set


Self
-
descriptive


media type (Content
-
Type)


text/html


application/
json


Includes metadata


Understood by all components


May be for humans, machines or both


Negotiated



Resources

Nouns
Unconstrained

Methods

Verbs
Constrained

Representations

Hyper Linked
Constrained

15

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

REST Modeling
-


How to design a
RESTful API



16

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

REST Modeling


Its different from:


Object modeling


Entity Relationship modeling


Resources are the key abstraction


What are the resources


What methods does each support


What representation(s) to use


Relationships via linking




17

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

REST Modeling
-

Resources


Start by identifying the resources


Similar to thinking about entities but...


Resources are not result sets (rows and columns)


They are “documents”


Two main types


Collections


Items




18

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

REST Modeling
-

URIs


Human readable (not necessary but it helps)


Tends to form a hierarchy


Use the query part appropriately


Use to search, filter, or possibly specify a mode


Identification of the resource is better in the path


(preferred) http://example.com/orders/100234


http://example.com/orders?id=100234


Don’t make them verbs!


(bad) http://example.com/accounts/addaccount



19

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

REST Modeling
-

Representations


The usual suspects:


text/html


application/xml


application/
json


application/x
-
www
-
form
-
urlencoded

(for input: PUT, POST)


And others: images:
svg
, jpg,
png

etc., text/
css
, text/
javascript


How many does each resource need?


Remember it is all about hyper media. Include links.



20

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

REST Modeling
-

Methods

But it’s not that simple …


REST

CRUD

SQL

GET

Read

SELECT

POST

Create

INSERT

PUT

Update or
Create

UPDATE or
INSERT

DELETE

Delete

DELETE

21

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

REST

CRUD

SQL

But …

GET

Read

SELECT

Keep it safe. Make sure there are

no side effects

POST

Create

INSERT

Also for other non
-
safe,

non
-
repeatable changes

PUT

Update or
Create

UPDATE or
INSERT

Keep it repeatable with same results
(idempotent)

DELETE

Delete

DELETE

Keep it repeatable with same results
(idempotent)

REST Modeling
-

Methods

22

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

REST Modeling
-

Methods


The difference between POST and PUT is in the meaning of the
request URI


For PUT the URI is the resource that will be created or updated


For POST the URI is the container of the resource that will be
created. The server gets to assign a URI to the resource


Conditional GET


Optimistic concurrency for PUT


Use method response codes appropriately




23

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

APEX RESTful Services
Use Cases



24

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Example Use Cases


Creating a native mobile application using same database as
corresponding APEX web application


Integration with back office operations


Data collection


Synchronization


Configuration management


Provide data persistence for a static single page web app


You have some interesting data you want to share with the world




25

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Reasons for using APEX
RESTful

Services


Implement resources close to the data


Leverage your experience with PL/SQL


Make use of existing logic in packages


Use existing APEX workspace and APEX Listener




26

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Considerations


APEX Listener is required


Keep up with the latest version


Demo’s were done using version 2.0.3


Authentication is needed for most real world situations


OAuth2 and APEX application authentication are supported


When making REST calls from a browser, either:


Serve the calling web page from the same origin, or


Use a modern browser that supports cross origin requests (CORS)


Another option is to make the call from the server




27

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

APEX RESTful Services
Architecture



28

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Architecture Diagram

Client

APEX

Listener

APEX

Builder

APEX

Metadata

29

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Definition metadata


RESTful

Service Module


Resource Templates


Handler



30

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

What the Listener does for you


Request dispatching


JSON generation for simple GET requests


Pagination


Lower cases column names


Null values are omitted


Generating JSON links


Simple JSON parsing, form data parsing


Exception and error handling and responses (HTML)




31

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Authentication


First party authentication


Standard APEX authentication


Must be in same workspace


Third party authentication


OAuth2


Authorization code flow


Implicit grant flow



32

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Handler Interface
-

Inputs


Pagination control


:
page_size
, :
page_offset
, :
row_offset
, :
row_count


For authenticated requests


:
current_user


Parameters from the URI template become bind variables


Request entity


:
content_type
, :body


Request entity


A simple JSON object is parsed and creates a bind
variable for each property. A x
-
www
-
form
-
urlencoded

body is parsed
and creates a bind variable for each parameter.


Any HTTP request header can be mapped to a bind variable


Special pseudo headers from listener


OWA environment OWA_UTIL.GET_CGI_ENV



33

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Handler Interface


Inputs continued


Special pseudo headers from Listener


X
-
APEX
-
BASE


the base URL of the request


X
-
APEX
-
PATH


the path of the request relative to the base


X
-
APEX
-
CHARSET


the character set of the request body


X
-
APEX
-
METHOD


the HTTP method used to make the request


X
-
APEX
-
PREFERRED
-
CONTENT
-
TYPE
-

from parsing the Accept
HTTP request, identifies the MOST preferred content type that the
client would like to receive



34

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Handler Interface
-

Outputs


Any HTTP response header can be mapped to a bind variable


OWA context:
htp.p

etc.


Special pseudo headers for Listener


X
-
APEX
-
STATUS
-

Specifies the numeric HTTP status code to
generate for the response


X
-
APEX
-
FORWARD
-

Specifies the location of a resource that
Listener should return as the response to this request.



35

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

APEX RESTful Services
Sample Walk Through



36

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Example
RESTful

Service Module


Uses the tables from the APEX Sample Database Application


DEMO_CUSTOMERS, DEMO_PRODUCT_INFO,
DEMO_ORDERS, DEMO_ORDER_ITEMS


APEX version 4.2.2, Listener 2.0.3


Uses pl/
json

open source JSON library


You need to install this library to use the sample


http://pljson.sourceforge.net/



37

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Common Pattern

employes
/


GET
-

Retrieves list of all employees.


POST
-

Create a new employee.


employes
/{
empno
}/


GET
-

Retrieves details for a specific employee.


PUT
-

Updates the specific employee.


DELETE
-

Deletes the employee.



38

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Testing Tips


Use APEX
RESTful

Services Test Client (resttest.html)


Use Firebug or developer tools to examine HTTP requests and
responses


Look at Error
-
Reason header


Do initial browser testing from same origin


Browsers hide error information when going cross origin


Another Java based test tool: rest
-
client from WizTools.org



39

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

Reference Material



40

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

REST References


RESTful

Web Services, by Leonard Richardson and Sam Ruby, available from
O’Reilly Media at
http://oreilly.com/catalog/9780596529260/


Wikipedia:
http://en.wikipedia.org/wiki/Representational_State_Transfer


The source:
http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm


mostly chapters 5 and 6


A nice 14 minute video introduction:
http://www.youtube.com/watch?v=YCcAE2SCQ6k


HTTP spec:
http://tools.ietf.org/html/rfc2616


URI spec:
http://tools.ietf.org/html/rfc3986


JSON format:
http://json.org/


Other specs like HTML, XML etc. from w3.org



41

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

APEX
RESTful

Services References


Application Express on OTN
http://otn.oracle.com/apex



The example module TBD


APEX
RESTful

Service Test Client TBD


RESTful

Services Dev Guide (restful_services_devguide.html) in the
Listener download zip file doc folder



42

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

@
vuvarovs

43

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.

44

Copyright © 2013, Oracle and/or its affiliates. All rights reserved.