Presentation is loading. Please wait.

Presentation is loading. Please wait.

Implementing RESTful Web Services with Oracle Application Express

Similar presentations

Presentation on theme: "Implementing RESTful Web Services with Oracle Application Express"— Presentation transcript:


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

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

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



Download ppt "Implementing RESTful Web Services with Oracle Application Express"

Similar presentations

Ads by Google