Res tful web services oracle

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)

www.oracle.com/technetwork/articles/javase/index-137171.html 1/8

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(yeOjc.ls)
jvxantto.eoretp=betcas
poetdWbevcCnetwCnet
rtce eSrieotx sotx;

pbi PrhsOdrevc( {
ulc ucaereSrie)
ty{
r
j =JXCnetnwntne"o.u.xmlsrs";
c ABotx.eIsac(cmsneape.et)

}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;


}
}
/ 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 Service



(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


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 3


/ 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 don't 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(" ",
Suc.ls,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
Suc.ls,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


Code Fragment 4 demonstrates how to make a similar P Trequest using the D s a c interface.
U ipth

Code Fragment 4


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


Code Sample 4


Figure 1 shows the display resulting from this code.



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 5




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
developer's 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/

Res tful web services oracle

More Related Content

What's hot (11)

Similar to Res tful web services oracle (20)

Res tful web services oracle