<html> | |
<head> | |
<meta http-equiv="content-type" content=""> | |
<title>RESTful Web Services Support</title> | |
</head> | |
<body lang="en"> | |
<h1>RESTful Web services Support</h1> | |
<p>REST provides access to resources through the two methods GET and POST. | |
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.</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 services requests and responses. REST Web services can be | |
accessed in two ways, i.e. using HTTP GET and POST.</p> | |
<h2>Doing REST web services with HTTP POST</h2> | |
<p>The REST default HTTP interface is POST. It can be enabled in the | |
Server/Client side by adding the following line to the axis2.xml file.</p> | |
<font color="blue">< parameter name="enableREST" locked="false" > true | |
</parameter> </font> | |
<p>It however acts as both a REST endpoint and SOAP endpoint. When a Message | |
is received, if the content type is text/xml and if the SOAP Action Headers | |
are missing, then the Message is treated as a RESTful Message. Else it is | |
treated as a usual SOAP Message.</p> | |
<p>On sending a message out, the fact that the message is RESTful or not, can | |
be decided from the client API or by deployment descriptor of the client.</p> | |
<ol> | |
<li>By adding an entry in the client repositories axis2.xml file.</li> | |
<li>Setting as a property in client API e.g. <source> | |
<pre>... | |
Options options = new Options(); | |
options.setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE); | |
...</pre> | |
</source></li> | |
</ol> | |
<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.setListenerTransportProtocol(Constants.TRANSPORT_HTTP); | |
options.setUseSeparateListener(false); | |
options.setProperty(Constants.Configuration.ENABLE_REST, Constants.VALUE_TRUE); | |
Call call = new Call(); | |
call.setClientOptions(options); | |
OMElement result = call.invokeBlocking("echo", 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.createText(value, "Axis2 Echo String ")); | |
method.addChild(value); | |
return method; | |
} | |
}</pre> | |
</source> | |
<h2>Access a REST Web Service Via HTTP GET</h2> | |
<p>Axis2 allow 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 in to XML and put in to the SOAP Body.</p> | |
<source><pre>http://127.0.0.1:8080/axis2/services/version/getVersion</pre> | |
</source> | |
<p>Result can be shown in the browser as follows:</p> | |
<img src="images/userguide/http-get-ws.png" alt="" /> | |
<p>For example, the following request, </p><source> | |
<pre>http://127.0.0.1:8080/axis2/services/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> | |
</body> | |
</html> |