xdocs/1_1/rest-ws.html - axis-axis2-java-core - Git at Google

 <html>

 <head>
   <meta http-equiv="content-type" content="">
   <title>RESTful Web Services Support</title>
   <link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
 </head>

 <body lang="en">

 <h1>RESTful Web Services Support</h1>

 <p>This document presents an introduction on REST and REST with HTTP POST &amp;
 GET.</p>

 <h2>Content</h2>
 <ul>
   <li><a href="#intro">Introduction</a></li>
   <li><a href="#rest_with_post">Doing REST Web Services with HTTP POST</a>
     <ul>
       <li><a href="#sample">Sample REST - HTTP POST Client</a></li>
     </ul>
   </li>
   <li><a href="#rest_with_get">Access a REST Web Service via HTTP GET</a></li>
 </ul>

 <a name="intro"></a>
 <h2>Introduction</h2>

 <p>WSDL 2.0 HTTP Binding defines a way to implement REST (Representational State Transfer) with Web services. Axis2 implements most defined in HTTP binding specification. REST Web services are a reduced subset of the usual Web service stack.</p>

 <p>The Axis2 REST implementation assumes the following properties:</p>
 <ol>
   <li>REST Web services are Synchronous and Request Response in nature.</li>
   <li>When REST Web services are accessed via GET, the service and the
     operations are identified based on the URL. The parameters are assumed as
     parameters of the Web service. In this case the GET based REST Web
     services supports only simple types as arguments and it should adhere to <a href="http://www.w3.org/TR/2006/CR-wsdl20-adjuncts-20060327/#_operation_iri_style">IRI style</a>.</li>
   <li>POST based Web services do not need a SOAP Envelope or a SOAP Body.
     REST Web Services do not have Headers and the payload is sent
   directly.</li>
 </ol>

 <p>Axis2 can be configured as a REST Container and can be used to send and
 receive RESTful Web service requests and responses. REST Web services can be
 accessed using HTTP GET and POST.</p>

 <a name="rest_with_post"></a>
 <h2>Doing REST Web Services with HTTP POST</h2>

 <p>Axis2 server, if REST is enabled, will act as both a REST endpoint and a SOAP endpoint. When a message is received, if the content type is text/xml and if the SOAPAction Header
 is missing, then the message is treated as a RESTful Message, if not it is
 treated as a usual SOAP Message.</p>

 <p>On sending a message, the fact that the message is RESTful or not, can
 be decided from the client API.<br>
 Set a property in the client api.<br>
 </p>
 <pre>...
 Options options = new Options();
 options.setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE);
 ...</pre>

 <a name="sample"></a>
 <h3>Sample REST - HTTP POST Client</h3>

 <p>There is an example named, userguide.clients.RESTClient.java which
 demonstrates the usage of the above, using the "echo"operation of the</p>
 <pre>userguide.example1.MyService </pre>

 <p>of the samples.The class source will be as follows:</p>
 <source><pre>public class RESTClient {

     private static String toEpr = "http://localhost:8080/axis2/services/MyService";

     public static void main(String[] args) throws AxisFault {

         Options options = new Options();
         options.setTo(new EndpointReference(toEpr));

         options.setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE);

         ServiceClient sender = new ServiceClient();
         sender.engageModule(new QName(Constants.MODULE_ADDRESSING));
         sender.setOptions(options);
         OMElement result = sender.sendReceive(getPayload());

         try {
             XMLStreamWriter writer = XMLOutputFactory.newInstance()
                     .createXMLStreamWriter(System.out);
             result.serialize(writer);
             writer.flush();
         } catch (XMLStreamException e) {
             e.printStackTrace();
         } catch (FactoryConfigurationError e) {
             e.printStackTrace();
         }
     }
     private static OMElement getPayload() {
         OMFactory fac = OMAbstractFactory.getOMFactory();
         OMNamespace omNs = fac.createOMNamespace(
                 "http://example1.org/example1", "example1");
         OMElement method = fac.createOMElement("echo", omNs);
         OMElement value = fac.createOMElement("Text", omNs);
         value.addChild(fac.createOMText(value, "Axis2 Echo String "));
         method.addChild(value);

         return method;
     }
 }</pre>
 </source>

 <a name="rest_with_get"></a>
 <h2>Access a REST Web Service via HTTP GET</h2>

 <p>Axis2 allows users to access Web services that have simple type parameters
 via HTTP GET. For example, the following URL requests the Version Service via
 HTTP GET. But the Web service arriving via GET assumes REST. Other parameters
 are converted into XML and put into the SOAP Body.</p>
 <source><pre>http://127.0.0.1:8080/axis2/rest/version/getVersion</pre>
 </source>
 <p>Result can be shown in the browser as follows:</p>
 <img src="images/userguide/http-get-ws.jpg"/><br clear="all"/>

 <p>For example, the following request,</p>
 <source><pre>http://127.0.0.1:8080/axis2/rest/version/getVersion</pre>
 </source>will be converted to the following SOAP Message for processing by
 Axis2.<source>
 <pre>
    &lt;soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"&gt;
       &lt;soapenv:Body&gt;
           &lt;axis2:getVersion xmlns:axis2="http://ws.apache.org/goGetWithREST" /&gt;
       &lt;/soapenv:Body&gt;
    &lt;/soapenv:Envelope&gt;
     </pre>
 </source>

 <h2>Resources</h2>

 <p>How I Explained REST to My Wife, By Ryan Tomayko- <a
 href="http://naeblis.cx/articles/2004/12/12/rest-to-my-wife">http://naeblis.cx/articles/2004/12/12/rest-to-my-wife</a></p>

 <p>Building Web Services the REST Way, By Roger L. Costello- <a
 href="http://www.xfront.com/REST-Web-Services.html">
 http://www.xfront.com/REST-Web-Services.html</a></p>

 <p>Resource-oriented vs. activity-oriented Web services, By James Snell- <a
 href="http://www-128.ibm.com/developerworks/webservices/library/ws-restvsoap/">http://www-128.ibm.com/developerworks/webservices/library/ws-restvsoap/</a></p>

 </body>

 </html>
	<html>

	<head>
	<meta http-equiv="content-type" content="">
	<title>RESTful Web Services Support</title>
	<link href="../css/axis-docs.css" rel="stylesheet" type="text/css" media="all" />
	</head>

	<body lang="en">

	<h1>RESTful Web Services Support</h1>

	<p>This document presents an introduction on REST and REST with HTTP POST &
	GET.</p>

	<h2>Content</h2>
	<ul>
	<li><a href="#intro">Introduction</a></li>
	<li><a href="#rest_with_post">Doing REST Web Services with HTTP POST</a>
	<ul>
	<li><a href="#sample">Sample REST - HTTP POST Client</a></li>
	</ul>
	</li>
	<li><a href="#rest_with_get">Access a REST Web Service via HTTP GET</a></li>
	</ul>

	<a name="intro"></a>
	<h2>Introduction</h2>

	<p>WSDL 2.0 HTTP Binding defines a way to implement REST (Representational State Transfer) with Web services. Axis2 implements most defined in HTTP binding specification. REST Web services are a reduced subset of the usual Web service stack.</p>

	<p>The Axis2 REST implementation assumes the following properties:</p>
	<ol>
	<li>REST Web services are Synchronous and Request Response in nature.</li>
	<li>When REST Web services are accessed via GET, the service and the
	operations are identified based on the URL. The parameters are assumed as
	parameters of the Web service. In this case the GET based REST Web
	services supports only simple types as arguments and it should adhere to <a href="http://www.w3.org/TR/2006/CR-wsdl20-adjuncts-20060327/#_operation_iri_style">IRI style</a>.</li>
	<li>POST based Web services do not need a SOAP Envelope or a SOAP Body.
	REST Web Services do not have Headers and the payload is sent
	directly.</li>
	</ol>

	<p>Axis2 can be configured as a REST Container and can be used to send and
	receive RESTful Web service requests and responses. REST Web services can be
	accessed using HTTP GET and POST.</p>

	<a name="rest_with_post"></a>
	<h2>Doing REST Web Services with HTTP POST</h2>

	<p>Axis2 server, if REST is enabled, will act as both a REST endpoint and a SOAP endpoint. When a message is received, if the content type is text/xml and if the SOAPAction Header
	is missing, then the message is treated as a RESTful Message, if not it is
	treated as a usual SOAP Message.</p>

	<p>On sending a message, the fact that the message is RESTful or not, can
	be decided from the client API.<br>
	Set a property in the client api.<br>
	</p>
	<pre>...
	Options options = new Options();
	options.setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE);
	...</pre>

	<a name="sample"></a>
	<h3>Sample REST - HTTP POST Client</h3>

	<p>There is an example named, userguide.clients.RESTClient.java which
	demonstrates the usage of the above, using the "echo"operation of the</p>
	<pre>userguide.example1.MyService </pre>

	<p>of the samples.The class source will be as follows:</p>
	<source><pre>public class RESTClient {

	private static String toEpr = "http://localhost:8080/axis2/services/MyService";

	public static void main(String[] args) throws AxisFault {

	Options options = new Options();
	options.setTo(new EndpointReference(toEpr));

	options.setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE);

	ServiceClient sender = new ServiceClient();
	sender.engageModule(new QName(Constants.MODULE_ADDRESSING));
	sender.setOptions(options);
	OMElement result = sender.sendReceive(getPayload());

	try {
	XMLStreamWriter writer = XMLOutputFactory.newInstance()
	.createXMLStreamWriter(System.out);
	result.serialize(writer);
	writer.flush();
	} catch (XMLStreamException e) {
	e.printStackTrace();
	} catch (FactoryConfigurationError e) {
	e.printStackTrace();
	}
	}
	private static OMElement getPayload() {
	OMFactory fac = OMAbstractFactory.getOMFactory();
	OMNamespace omNs = fac.createOMNamespace(
	"http://example1.org/example1", "example1");
	OMElement method = fac.createOMElement("echo", omNs);
	OMElement value = fac.createOMElement("Text", omNs);
	value.addChild(fac.createOMText(value, "Axis2 Echo String "));
	method.addChild(value);

	return method;
	}
	}</pre>
	</source>

	<a name="rest_with_get"></a>
	<h2>Access a REST Web Service via HTTP GET</h2>

	<p>Axis2 allows users to access Web services that have simple type parameters
	via HTTP GET. For example, the following URL requests the Version Service via
	HTTP GET. But the Web service arriving via GET assumes REST. Other parameters
	are converted into XML and put into the SOAP Body.</p>
	<source><pre>http://127.0.0.1:8080/axis2/rest/version/getVersion</pre>
	</source>
	<p>Result can be shown in the browser as follows:</p>
	<img src="images/userguide/http-get-ws.jpg"/><br clear="all"/>

	<p>For example, the following request,</p>
	<source><pre>http://127.0.0.1:8080/axis2/rest/version/getVersion</pre>
	</source>will be converted to the following SOAP Message for processing by
	Axis2.<source>
	<pre>
	<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
	<soapenv:Body>
	<axis2:getVersion xmlns:axis2="http://ws.apache.org/goGetWithREST" />
	</soapenv:Body>
	</soapenv:Envelope>
	</pre>
	</source>

	<h2>Resources</h2>

	<p>How I Explained REST to My Wife, By Ryan Tomayko- <a
	href="http://naeblis.cx/articles/2004/12/12/rest-to-my-wife">http://naeblis.cx/articles/2004/12/12/rest-to-my-wife</a></p>

	<p>Building Web Services the REST Way, By Roger L. Costello- <a
	href="http://www.xfront.com/REST-Web-Services.html">
	http://www.xfront.com/REST-Web-Services.html</a></p>

	<p>Resource-oriented vs. activity-oriented Web services, By James Snell- <a
	href="http://www-128.ibm.com/developerworks/webservices/library/ws-restvsoap/">http://www-128.ibm.com/developerworks/webservices/library/ws-restvsoap/</a></p>

	</body>

	</html>