2. Implementing RESTful Web Services with Oracle Application Express

3. 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. 3 3

4. 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. Introduction to REST

6. 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, ...
What can REST do for you? Just another way to provide access to data/services.
Just a small sample, there are many others
Use in products and tools may be internal rather than for 3rd party use
This talk focuses on how to define your own RESTful API/Service for either public or private use

7. 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
REST is an architectural style.
By Web I mean the world wide web but also the specifications it is built on URI, HTTP, HTML etc (these are the technology foundations of the web).
Term RESTful used for systems that follow the REST style
Not specific to web services.
Roy was an author of the HTTP specification among other work on the early Web since 1993.
The paper is about what makes the Web at large work not any particular web site/app/page
The ideas that make up REST were developed along side the creation of the Web but different terms were used.
Link to Roy’s paper and other resources given at the end.

8. 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
As a web developer (or API designer) what parts of the architecture are under your control?
Client-server request response and layered are out of your control.
Some may make recommendations about intermediaries
That leaves stateless, caching, uniform interface and code on demand
There is nothing to enforce that you are using HTTP in a RESTful way
Uniform interface is the most interesting (and distinguishing) point for web service design.

9. 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
Quote is from Roy Fielding’s dissertation

10. 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
Stateless is key to scale and performance. Client isn’t limited to talking to just one server.
Server can reboot/be upgraded. No complicated session replication.
The web browser isn’t the only client (user-agent).
Following REST means that your resource is available to spiders, wget and other tools, mashups etc.

11. Uniform Interface The REST Triangle: Resources
Methods
Representations
Resources Nouns Unconstrained
Roy’s paper treated hypermedia as separate from representations other places it is part of representations.
Methods Verbs Constrained
Representations Hyper Linked Constrained

12. 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:
Resources Nouns Unconstrained
The key thing is the set of all resources is unconstrained
A resource can be anything – even the result of a calculation May be static or dynamic
A simple/clean URI by itself != REST
Resource is the target of a hyper link reference
Methods Verbs Constrained
Representations Hyper Linked Constrained

13. 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
Constrained on purpose so all clients can operate on all resources
Safe means no side effects, the resource isn’t changed
Idempotent means repeatable with the same results
HEAD is another method it is like GET but only returns the headers
There are a few others some in the webdav space and PATCH
New methods would have to be widely useful to many/all resources and understood by clients, servers, and intermediaries
Often related to CRUD database operations but not an exact mapping
With post the created resource is named by the server
Methods Verbs Constrained
Representations Hyper Linked Constrained

14. 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
Set of representations is constrained but more frequently extended than methods. For example application/json was added recently
Components are clients/browser (user-agent), web servers (origin server), gateways, proxies etc.
Typically think of the response but representations can also be in the request (for PUT and POST) but understood media types more limited.
Can think of representations as data types
Self-descriptive means well defined semantics for all the parts of the message that client, server and everything in between can know about. Also the metadata tells you what type the message is and what you can do with it i.e. cache etc.
Negotiation: not back and forth: client says what it can accept using Accept header (list with preference (q)). Server picks best it can supply. Server says what it returned in Content-Type header
Remember: You can’t trust the client – validate inputs
Robustness principal: be liberal in what you accept, be conservative in what you send
Methods Verbs Constrained
Representations Hyper Linked Constrained

15. REST Modeling - How to design a RESTful API

16. 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
REST modeling should be easier for people with database background compared with OO background
- already have fixed set of operations SELECT INSERT etc.

17. 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
Think about what data the client needs
The resources may contain multiple sets of data.
They tend to be large grained rather than fine grained
Could be a mix of items and collections
A single table may have multiple resources. Think about how database views are used.

18. 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)
Don’t make them verbs!
(bad)
Consistent well organized URIs helps
There are syntax rules for web URIs scheme, authority, path, query, fragment (last 3 are in the domain of your design)
I see no problem with hackable or guess able URIs – this means that given a few examples the user could guess (with a good chance of being right) about what other URIs might work.
Identifying entities: numbers, guids, natural keys
Don’t change URIs needlessly. Consider keeping old ones around.
Think before changing URIs consider keeping the old ones around

19. 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.
If the semantics/content changes from one rep to another it should be a different resource.
If representation doesn’t include URIs then must document how client can form URIs from other embedded identifiers

20. REST Modeling - Methods
CRUD
SQL
GET
Read
SELECT
POST
Create
INSERT
PUT
Update or Create
UPDATE or INSERT
DELETE
Delete
But it’s not that simple …

21. REST Modeling - Methods
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

22. 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
Don’t make up response codes in your message that HTTP already has
Optimistic concurrency for put: If-unmodified-since header and 412 precondition failed response code

23. APEX RESTful Services Use Cases

24. 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. 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. 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
WRT web apps that need data from web services, For SOAP or other protocols there was no choice but to have the server act as client to the remote service
With REST and ajax/xhr there is the possibility for the client to call the remote service directly.
Doing REST from the server is less efficient. When the RESTful service is on the same instance as the APEX app it doesn’t make much sense to call from the server. Often dynamic actions are a better choice.

27. APEX RESTful Services Architecture

28. Architecture Diagram APEX Listener Client APEX Builder APEX Metadata
Client: browser, mobile, desktop, server, anything that talks HTTP
APEX Listener: is the core: request routing, URI parsing, all default behavior
APEX Builder SQL Workshop for editing the RESTful service definitions
APEX Metadata persistence for RESTful service definitions
All processing happens in either the Listener or in your resource handlers

29. Definition metadata
RESTful Service Module
Resource Templates
Handler

30. 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)
Can’t easily support query parameters. Also no built-in support for matrix parameters – because {param} must match something
For default JSON generation you don’t get full control over the output.
A . or .. prefix can be used in generating link URIs
JSON parsing can’t handle nested objects or arrays.
You can get around any of these limitations with a little more effort.
It also does authentication
Entity tag handling, cache control headers

31. Authentication First party authentication Standard APEX authentication
Must be in same workspace
Third party authentication
OAuth2
Authorization code flow
Implicit grant flow
First party means the API/service is uses its own authentication. APEX RESTful web services leverages the authentication used by APEX
Just need to set the Apex-Session header with the app ID and session ID
Third party means the API/services lets a third party authenticate the user. The third party just tells the service the user is who they say they are.
OAuth2 is a complex protocol with many options and flows.
Listener supports just two flows.
In the end it comes down to sending an Authorization header with an access token
This is all explained well in the restful_services_devguide that comes in the listener zip download

32. 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
Some of this information is not fully documented currently.
Currently best source of information is restful_services_devguide that comes in the listener zip download

33. 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
These pseudo headers are made available as bind variables just like normal request headers

34. 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.
These pseudo headers are made available as bind variables just like normal response headers

35. APEX RESTful Services Sample Walk Through

36. 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

37. 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. 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. Reference Material

40. REST References
RESTful Web Services, by Leonard Richardson and Sam Ruby, available from O’Reilly Media at
Wikipedia:
The source: mostly chapters 5 and 6
A nice 14 minute video introduction:
HTTP spec:
URI spec:
JSON format:
Other specs like HTML, XML etc. from w3.org

41. APEX RESTful Services References
Application Express on OTN
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. @vuvarovs