Presentation is loading. Please wait.

Presentation is loading. Please wait.

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

Similar presentations


Presentation on theme: "1 Copyright © 2013, Oracle and/or its affiliates. All rights reserved."— Presentation transcript:

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

2 2 Implementing RESTful Web Services with Oracle Application Express

3 3 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. The following is intended to outline Oracles 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 Oracles products remains at the sole discretion of Oracle.

4 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 5 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. Introduction to REST

6 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 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. Its a description of how the Web works and why it works well

8 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 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 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 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 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 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 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 15 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. REST Modeling - How to design a RESTful API

16 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 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 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 Dont make them verbs! (bad) http://example.com/accounts/addaccount

19 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 20 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. REST Modeling - Methods But its not that simple … RESTCRUDSQL GETReadSELECT POSTCreateINSERT PUTUpdate or Create UPDATE or INSERT DELETEDeleteDELETE

21 21 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. RESTCRUDSQLBut … GETReadSELECTKeep it safe. Make sure there are no side effects POSTCreateINSERTAlso for other non-safe, non-repeatable changes PUTUpdate or Create UPDATE or INSERT Keep it repeatable with same results (idempotent) DELETEDeleteDELETEKeep it repeatable with same results (idempotent) REST Modeling - Methods

22 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 23 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. APEX RESTful Services Use Cases

24 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 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 26 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. Considerations APEX Listener is required Keep up with the latest version Demos 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 27 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. APEX RESTful Services Architecture

28 28 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. Architecture Diagram Client APEX Listener APEX Builder APEX Metadata

29 29 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. Definition metadata RESTful Service Module Resource Templates Handler

30 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 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 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 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 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 35 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. APEX RESTful Services Sample Walk Through

36 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 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 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 39 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. Reference Material

40 40 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. REST References RESTful Web Services, by Leonard Richardson and Sam Ruby, available from OReilly Media at http://oreilly.com/catalog/9780596529260/http://oreilly.com/catalog/9780596529260/ Wikipedia: http://en.wikipedia.org/wiki/Representational_State_Transferhttp://en.wikipedia.org/wiki/Representational_State_Transfer The source: http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm mostly chapters 5 and 6http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm A nice 14 minute video introduction: http://www.youtube.com/watch?v=YCcAE2SCQ6k http://www.youtube.com/watch?v=YCcAE2SCQ6k HTTP spec: http://tools.ietf.org/html/rfc2616http://tools.ietf.org/html/rfc2616 URI spec: http://tools.ietf.org/html/rfc3986http://tools.ietf.org/html/rfc3986 JSON format: http://json.org/http://json.org/ Other specs like HTML, XML etc. from w3.org

41 41 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. APEX RESTful Services References Application Express on OTN http://otn.oracle.com/apexhttp://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 42 Copyright © 2013, Oracle and/or its affiliates. All rights reserved. @vuvarovs

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

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


Download ppt "1 Copyright © 2013, Oracle and/or its affiliates. All rights reserved."

Similar presentations


Ads by Google