Res tful web services oracle


Published on

  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Res tful web services oracle

  1. 1. 6/16/12 RESTful Web Services ( Sign In/Register for Account | Help ) United States Communities I am a... I want to... Secure Search Products and Services Solutions Downloads Store Support Training Partners About Oracle Technology Netw ork Oracle Technology Network Articles Java Platform, Standard Edition Application Development RESTful Web Services Framework By Sameer Tyagi, August 2006 Application Express Articles Index Big Data In software engineering, the term software architectural style generally refers to "a set of design rules that identify the kinds of components and Business Intelligence connectors that may be used to compose a system or subsystem." * Some common examples of architectural styles include the Pipe and Filter, Cloud Computing Layered, Push Based, and so on. In the web services world, REpresentational State Transfer (REST) is a key design idiom that embraces a stateless client-server architecture in which the web services are viewed as resources and can be identified by their URLs. Web service clients that Communications want to use these resources access a particular representation by transferring application content using a small globally defined set of remote Database Performance & methods that describe the action to be performed on the resource. REST is an analytical description of the existing web architecture, and thus the Availability interplay between the style and the underlying HTTP protocol appears seamless. Data Warehousing The HTTP methods such as G Tand P S are the verbs that the developer can use to describe the necessary create, read, update, and delete E OT .NET (CRUD) actions to be performed. Some may see an analogy to operations in SQL, which also relies on a few common verbs, as shown in Table 1. However, the REST style and HTTP protocol are mutually exclusive, and REST does not require HTTP. Dynamic Scripting Languages Table 1: Relationships Between SQL and HTTP Verbs Embedded Action SQL HTTP Social Enterprise Create I s r P T netU Enterprise Architecture Read S l c G T eetE UpdateU d t P S paeOT Enterprise Management Delete D l t D L T eeeEEE Identity & Security When to Use REST Java Architects and developers need to decide when this particular style is an appropriate choice for their applications. A RESTFul design may be appropriate when Linux Service-Oriented The web services are completely stateless. A good test is to consider whether the interaction can survive a restart of the server. Architecture A caching infrastructure can be leveraged for performance. If the data that the web service returns is not dynamically generated and can be cached, SQL & PL/SQL then the caching infrastructure that web servers and other intermediaries inherently provide can be leveraged to improve performance. However, Server and Storage the developer must take care because such caches are limited to the HTTP G Tmethod for most servers. E Administration The service producer and service consumer have a mutual understanding of the context and content being passed along. Because there is no Server and Storage formal way to describe the web services interface, both parties must agree out of band on the schemas that describe the data being exchanged Development and on ways to process it meaningfully. In the real world, most commercial applications that expose services as RESTful implementations also Systems Hardware and distribute so-called value-added toolkits that describe the interfaces to developers in popular programming languages. Architecture Bandwidth is particularly important and needs to be limited. REST is particularly useful for limited-profile devices such as PDAs and mobile Systems phones, for which the overhead of headers and additional layers of SOAP elements on the XML payload must be restricted. Web service delivery or aggregation into existing web sites can be enabled easily with a RESTful style. Developers can use technologies such as Asynchronous JavaScript with XML (AJAX) and toolkits such as Direct Web Remoting (DWR) to consume the services in their web applications. Rather than starting from scratch, services can be exposed with XML and consumed by HTML pages without significantly refactoring the existing web site architecture. Existing developers will be more productive because they are adding to something they are already familiar with, rather than having to start from scratch with new technology. A SOAP-based design may be appropriate when A formal contract must be established to describe the interface that the web service offers. The Web Services Description Language (WSDL) describes the details such as messages, operations, bindings, and location of the web service. The architecture must address complex nonfunctional requirements. Many web services specifications address such requirements and establish a common vocabulary for them. Examples include Transactions, Security, Addressing, Trust, Coordination, and so on. Most real-world applications go beyond simple CRUD operations and require contextual information and conversational state to be maintained. With the RESTful approach, developers must build this plumbing into the application layer themselves. The architecture needs to handle asynchronous processing and invocation. In such cases, the infrastructure provided by standards such as WSRM and APIs such as JAX-WS with their client-side asynchronous invocation support can be leveraged out of the box. RESTful Support in JAX-WS The Java API for XML Web Services (JAX-WS) provides full support for building and deploying RESTful web services. The API was developed through the Java Community Process program as JSR 224. It is tightly integrated with the Java Architecture for XML Binding (JAXB) for binding XML to Java technology data and is included in both the Java Platform, Standard Edition (Java SE) 6 and the Java Platform, Enterprise Edition (Java EE) 5. Building RESTful Services The example used in this section builds on the purchase order service described in the Java EE BluePrints catalog as the "Patterns and Design" white papers (Parts 1, 2, and 3). The original endpoint contained only one method -- a c p P -- that accepted a P r h s O d rand returned a cetO ucaere P r h s O d r t t s both of which were defined by individual schemas. ucaereSau, Table 2 shows some more CRUD operations to add to this service. Table 2: Additional CRUD Operations Description Java Technology Method Signature Create a new order pbi Prhs OdrttsacpP(ucaere odr ulc ucae reSau cetOPrhsOdr re) 1/8
  2. 2. 6/16/12 RESTful Web Services Retrieve an existing order pbi PrhsOdrrtivP (tigodrD ulc ucaere ereeO Srn reI) Modify an existing order pbi PrhsOdrudtP(ucaere odr ulc ucaere paeOPrhsOdr re) Cancel an order already submittedp b i v i c n e P ( t i g o d r D ulc od aclOSrn reI) JAX-WS enables building RESTful endpoints through a j v x x l w . r v d rinterface in the API. P o i e is a generic interface that can be aa.m.sPoie rvdr implemented by a class as a dynamic alternative to a service endpoint interface (SEI), and a service implementing this interface can be deployed in a Java EE container or published in a stand-alone mode through the JAX-WS E d o n API. The P o i e interface contains a single method with npit rvdr the following signature: Tivk( rqet noeT eus) P o i e is a low-level generic API, but using it requires the endpoint to have an intimate knowledge of the desired message or payload structure rvdr being passed to the service. Depending on how the p o i e is implemented, the supported types for Tand their uses are the following: rvdr j v x x l t a s o m S u c . Allows the p o i e to generate and consume XML directly aa.m.rnfr.ore rvdr j v x a t v t o . a a o r e. Works with MIME-typed messages aa.ciainDtSuc j v x x l s a . O P e s g . Conveniently works with and manipulates the entire SOAP message aa.m.opSAMsae The S r i e o eannotation is used to configure the messaging mode of a P o i e instance. With @ e v c M d ( a u = E S G ) the evcMd rvdr SrieoevleMSAE, provider will receive and return entire protocol messages -- for example, a SOAP message when using the SOAP binding. With @ e v c M d ( a u = A L A ) the runtime will pass only the message payload on to the provider -- for example, the contents of a SOAP B d SrieoevlePYOD, oy element when using the SOAP binding. This is useful when you want to build a WSDL-based web service but want to directly access the XML in the payload and return XML directly as well. For details, refer to the "Switching off Data Binding" strategy in this previous article. Code Sample 1 shows a simple stand-alone provider that, when accessed by browsing to h t : / 2 . . . : 0 4 h l o w r d returns the tp/1700188/el/ol, XML message < > e l w r d / > Note: The URLs provided in this article are for demonstration purposes only and are not live links. phlo ol<p. Code Sample 1 @eSriervdr WbevcPoie @evcMd(au=evc.oePYOD SrieoevleSrieMd.ALA) pbi casMPoie ipeet Poie<ore { ulc ls yrvdr mlmns rvdrSuc> pbi Suc ivk(oresuc){ ulc ore noeSuc ore Srn rpylmn =nwSrn(<>el wrd/>) tig elEeet e tig"phlo ol<p"; SraSuc rpy=nwSraSuc( temore el e temore nwSrnRae(elEeet) e tigedrrpylmn); rtr rpy eun el; } pbi sai vi mi(tigag[){ ulc ttc od anSrn rs] Edon e=Edon.rae HTBnigHT_IDN, npit npitcet( TPidn.TPBNIG nwMPoie() e yrvdr); epbih"tp/1700188/el/ol"; .uls(ht:/2...:04hlowrd) / Rnfrvr eso(; / u oee .tp) } } Code Sample 2 shows an extract for the P r h s O d r e v c class that implements a P o i e interface. The service processes the four ucaereSrie rvdr main HTTP methods and invokes business operations in their context. Table 3 lists the operation invoked, the sample HTTP request, the HTTP response, and the Java technology method. It is useful -- though not required -- to include the schemas representing the data exchanged and other documentation with the endpoint Web ARchive (WAR) so that clients can inspect them and reference them as needed. Code Sample 2 @aa.m.sWbevcPoie jvxxlw.eSriervdr @aa.m.sSrieoevlejvxxlw.evc.oeMSAE jvxxlw.evcMd(au=aa.m.sSrieMd.ESG) pbi casPrhsOdrevc ipeet Poie<ore{ ulc ls ucaereSrie mlmns rvdrSuc> piaeJXCnetj; rvt ABotx c @aa.noainRsuc( jvxantto.eoretp=betcas poetdWbevcCnetwCnet rtce eSrieotx sotx; pbi PrhsOdrevc( { ulc ucaereSrie) ty{ r j =JXCnetnwntne"o.u.xmlsrs"; c ABotx.eIsac( }cthJXEcpinj){ ac(ABxeto e trwnwWbevcEcpin"antcet JXCnet,j) ho e eSriexeto(Cno rae ABotx" e; } } pbi Suc ivk(oresuc){ ulc ore noeSuc ore ty r{ Msaeotx m =wCnetgtesgCnet) esgCnet c sotx.eMsaeotx(; Srn pt =(tigm.e(esgCnetPT_NO; tig ah Srn)cgtMsaeotx.AHIF) Srn mto =(tigm.e(esgCnetHT_EUS_EHD; tig ehd Srn)cgtMsaeotx.TPRQETMTO) i (ehdeul(GT) f mto.qas"E") rtr gtm) eun e(c; i (ehdeul(PS") f mto.qas"OT) rtr ps(ore m) eun otsuc, c; i (ehdeul(PT) f mto.qas"U") rtr ptsuc,m) eun u(ore c; i (ehdeul(DLT") f mto.qas"EEE) rtr dlt(ore m) eun eeesuc, c; trwnwWbevcEcpin"nupre mto: +ehd; ho e eSriexeto(Uspotd ehd" mto) }cthJXEcpinj){ ac(ABxeto e trwnwWbevcEcpinj) ho e eSriexeto(e; 2/8
  3. 3. 6/16/12 RESTful Web Services } } / Ohrmtosntsonhr / te ehd o hw ee With RESTFul web services, there is a natural mapping between the HTTP methods and most CRUD-like business operations that many services expose. Though there are no hard and fast rules, the following general guidelines are applicable for most cases: G Tis used to retrieve data or perform a query on a resource. The data returned from the web service is a representation of the requested E resource. P S is used to create a new resource. The web service may respond with data or status indicating success or failure. OT P Tis used to update existing resources or data. U D L T is used to remove a resource or data. EEE In some cases, the update and delete actions may be performed with P S operations as well, for example, when the services are consumed by OT browsers that do not support P Tor D L T . The GlassFish application server and the JAX-WS API support all four HTTP operations shown in Table U EEE 1. Table 3 shows the HTTP request and HTTP response messages for the operation in the implementation of the purchase order service. Table 3: HTTP Request and HTTP Response Messages for the Purchase Order 3/8
  4. 4. 6/16/12 RESTful Web Services (Click here for larger sample.) Use cases in which the service needs to indicate an exception can do this by setting the appropriate HTTP status code and response message on the M s a e o t x . For example, a response to an order retrieval process with an invalid ID can be implemented by setting the HTTP 400 status esgCnet code and including the XML from the P P o e s n P o l m x dschema. Code Fragment 1 illustrates this. Orcsigrbe.s Code Fragment 1 (Click here for larger sample.) Strategy: Implement the verb as part of the URI. To process a purchase order, make an HTTP request to the URL h t : / 2 . . . : 0 0 r s f l e s r i e w r p s r i e a c p P tp/1700188/etuwbevc-a/oevc/cetO The service or resource interprets the verb in the URI as the action that it must perform. The service retrieves the necessary data from the request, which physically can be an HTTP G Tor P S , and it returns data based on the P r h s O d r x dschema. E OT ucaere.s Strategy: Use the protocol method to describe the verb or operation. To retrieve a purchase order in which the order ID is ABC123, make an HTTP request using a G Toperation. In this case, the requested URL would E be h t : / 2 . . . : 0 0 r s f l e s r i e w r p s r i e A C 2 tp/1700188/etuwbevc-a/oevc/B13 Following is a sample HTTP request: GT/etuwbevc-a/oevc/B13HT/. E rsflesriewrpsrieAC2 TP10 Acp-agae e-s cetLnug: nu Cneto:coe oncin ls CnetTp:tx/m otn-ye etxl Hs:1700199 ot 2...:00 To cancel a purchase order in which an order ID is ABC123, make an HTTP request using a D L T operation. In this case, the URL would also be EEE ht:/2...:00rsflesriewrpsrieAC2 tp/1700188/etuwbevc-a/oevc/B13 Following is a sample HTTP request: DLT /etuwbevc-a/oevc/B13HT/. EEE rsflesriewrpsrieAC2 TP10 Acp-agae e-s cetLnug: nu Cneto:coe oncin ls CnetTp:tx/m otn-ye etxl Hs:1700199 ot 2...:00 Pam:n-ah rga occe Consuming RESTful Services Applications can access RESTful services in one of two ways: programmatically or by using browsers. Accessing Services Programmatically JAX-WS enables a client to consume RESTful web services programmatically. The main API is the j v x x l w . i p t hinterface described in aa.m.sDsac Code Sample 3. Code Sample 4/8
  5. 5. 6/16/12 RESTful Web Services / Ti temsaetp. / s h esg ye pbi itraeDsac<>{ ulc nefc ipthT / snhoosrqetrsos / ycrnu eus-epne Tivk( mg; noeT s) / aycrqetrsos / sn eus-epne Rsos<>ivkAycTmg; epneT noesn( s) Ftr<>ivkAycTmg Aycade<>h; uue? noesn( s, snHnlrT ) / oewy / n-a vi ivkOea( mg; od noenWyT s) } Unlike the P o i e on the server side, developers dont actually implement this API. Instead, they obtain an instance from the S r i eobject as rvdr evc shown here: srie=Sriecet(nm) evc evc.raeqae; srieadotqae HTBnigHT_IDN,ul; evc.dPr(nm, TPidn.TPBNIG r) Dsac<ore dsace =sriecetDsac(e Qae",") ipthSuc> ipthr evc.raeipthnw Nm(" ",,SrieMd.ALA) orecas evc.oePYOD; The typed D s a c < >interface and the i v k method can accept and return four major datatypes: ipthT noe D s a c < a a . m . r n f r . o r e . Useful for HTTP binding payload mode ipthjvxxltasomSuc> D s a c < a a . m . o p S A M s a e . Useful for SOAP message mode ipthjvxxlsa.OPesg> D s a c < a a . c i a i n D t S u c >. Useful for handling MIME messages ipthjvxatvto.aaore D s a c < b e t . Useful for payload mode with JAXB binding ipthOjc> Code Fragment 2 demonstrates how to make a P S request to h t : / 2 . . . : 0 0 r s f l e s r i e w r p s r i e a c p P OT tp/1700188/etuwbevc-a/oevc/cetO with the XML as the body of the P S request read from a string. OT Code Fragment 2 piaevi acpP( { rvt od cetO) Sriesrie=Sriecet(nm) evc evc evc.raeqae; srieadotqae HTBnigHT_IDN,ul+"cetO) evc.dPr(nm, TPidn.TPBNIG r acpP"; Dsac<ore dsace =sriecetDsac(nm, ipthSuc> ipthr evc.raeipthqae,SrieMd.ESG) orecas evc.oeMSAE; MpSrn,Ojc>rqetotx =dsace.eRqetotx(; a<tig bet eusCnet ipthrgteusCnet) rqetotx.u(esgCnetHT_EUS_EHD "OT) eusCnetptMsaeotx.TPRQETMTO, PS"; Suc rsl =dsace.noenwSraSuc(e SrnRae(oM)) ore eut ipthrivk(e temorenw tigedrpXL); pitorersl) rnSuc(eut; } Code Fragment 3 demonstrates how to make a similar POST request, but it differs from Code Fragment 2 in that it sends and returns JAXB- generated objects rather than handling strings directly. Code Fragment 3 (Click here for larger sample.) Code Fragment 4 demonstrates how to make a similar P Trequest using the D s a c interface. U ipth Code Fragment 4 (Click here for larger sample.) Accessing Services Using Browsers Because RESTful web services deployed in JAX-WS are exposed using the standard HTTP protocol and methods, they can be easily accessed from browsers. In addition to using simple G Tand P S requests directly from browsers, developers can leverage the capabilities of the JavaScript E OT technology X L t p e u s object that most modern browsers support. This is the same object used for building AJAX user interfaces (UIs). MHtRqet Code Sample 4 shows a simple script that is included with the downloadable sample code and test client that you can use to test RESTful web services from 5/8
  6. 6. 6/16/12 RESTful Web Services Code Sample 4 (Click here for larger sample.) Figure 1 shows the display resulting from this 6/8
  7. 7. 6/16/12 RESTful Web Services Figure 1: Resulting Display (Click image for larger view.) Describing RESTful Endpoints Unlike SOAP-based web services, which have a standard vocabulary to describe the web service interface through WSDL, RESTful web services currently have no such grammar. For a service consumer to understand the context and content of the data that must be sent to and received from the service, both the service consumer and service producer must have an out-of-band agreement. This takes the form of documentation, sample code, and an API that the service provider publishes for developers to use. For example, the many web-based services available from Google, Yahoo, Flickr, and so on have accompanying artifacts describing how to consume the services. If you are developing RESTful web services, the following general guidelines provide a good starting point: Make the XML schemas available to service consumers and package them with the WAR file. Clearly document the expected input, output, and error conditions that may arise as result of invocation. Web Application Description Language (WADL) The style of documenting RESTful web services that this article has previously described is fine for use by developers, but it prevents tools from programmatically consuming such services and generating artifacts specific to programming languages. For example, a WSDL file can be consumed by various tools and proxies or by generated stubs that applications can use directly. A research effort from Sun Labs called Web Application Description Language (WADL) attempts to resolve some of these issues by providing a means to describe services in terms of schemas, HTTP methods, and the request or response structures exchanged. The schema in Code Sample 5 shows a sample WADL description for the example discussed previously. Code Sample 7/8
  8. 8. 6/16/12 RESTful Web Services (Click here for larger sample.) Summary JAX-WS provides comprehensive support for building web services. Developers can leverage the capabilities of this API to build and consume a variety of web services, whether those services are based on WSDL or are RESTful in behavior. The combination of the P o i e and D s a c rvdr ipth interfaces allows web services to be built and consumed, and it provides developers with the flexibility to process the messages sent over the wire in a variety of ways. In addition, the future holds the possibility of describing RESTful web services for tools to consume, which will further simplify the developers experience. For More Information Toward Boxology: Preliminary Classification of Architectural Styles, by M. Shaw and P. Clements Downloadable sample code and test client Architectural Styles and the Design of Network-based Software Architectures, by Roy Thomas Fielding Java API for XML Web Services (JAX-WS) JSR 224: Java API for XML-Based Web Services (JAX-WS) 2.0 Web Application Description Language (WADL) Patterns and Strategies for Building Document-Based Web Services: Part 1 in a Series Interoperability With Patterns and Strategies for Document-Based Web Services: Part 2 in a Series Realizing Strategies for Document-Based Web Services With JAX-WS 2.0: Part 3 in a Series About the Author Sameer Tyagi is a senior staff engineer at Sun Microsystems with the Web Services group. He remains focused on architecture, design, and implementation of large-scale enterprise applications with Java technology. Among his publications are industry periodicals and books on Java and Java EE technologies, as well as a blog. Rate and Review Tell us what you think of the content of this page. Excellent Good Fair Poor Comments: <t> /d <t> /r <r t> <d t> <togYu ealades(orpyi psil wtota srn>or mi drs n el s osbe ihu n ades:/tog drs)<srn> <r> b/ < he=ht:/u.o/rvc/ a rf"tp/sncmpiay" tre=_e"SnPiayPlc<a agt"nw>u rvc oiy/> <r> b/ 8/8