| <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 is providing access to resources through the two methods GET and |
| POST. The REST Web services are reduced subset of the usual Web Service |
| stack, and the Axis2 REST implementation assumes following properties.</p> |
| <ol> |
| <li>REST Web services are Synchronous, and Request Response in nature.</li> |
| <li>When the REST Web Services are accessed via GET, the service and the |
| operations are identified based on the URL and 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 directly |
| sent.</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. The REST Web Services |
| can be access in two ways, i.e. using HTTP GET and POST.</p> |
| |
| <h2>Doing REST web services with HTTP POST</h2> |
| |
| <p>REST's 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>But it acts both as a REST endpoint as well as a 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 |
| <source></p> |
| <pre>userguide.example1.MyService </pre> |
| |
| <p>of the samples. And the class source will be as follows:</p> |
| |
| <p><source></p> |
| <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 lets the user to access Web Services that has simple type parameters |
| via the HTTP GET. For example the following URL requests the Version Service |
| via HTTP GET. But the web service arrives via GET assumes REST . Other |
| parameters are converted in to XML and put them 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"> |
| |
| <p>For an example, the following request, <source></p> |
| <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> |