How to REST?! - Example: Authentication Service

As an example we are going to develop an authentication service. This service receives an xml document as input and returns an xml document as output. The input xml document contains username and password which needs to be authenticated and the output xml contains a simple XML message to return the result of authentication to the client.
As the first step, we need to define an interface for our service to format the incoming and outgoing XML documents.Almost all the SOAP-based SOA applications use WSDL to define their interfaces, but in the RESTful application there is no WSDL to use. So we need to find another way for defining our service interfaces.One of the most widely used approaches is using XML Schema.In this example we use a simple XML Schema to restrict the input and output xml messages to our desired format.

So:
1. XML documents are used to exchange messages between applications.
2. XML Schema documents define the application interfaces.

Example of incoming XML document:

<auth xmlns="http://www.javadev.org/auth" xsi="http://www.w3.org/2001/XMLSchema-instance" schemalocation="http://www.javadev.org/auth http://javadev.org/rest/auth/auth.xsd">
<username>foo</username>
<password>foo</password>
</auth>


Example of the schema used as the interface:

<schema xmlns="http://www.w3.org/2001/XMLSchema" elementformdefault="qualified" targetnamespace="http://www.javadev.org/auth" auth="http://www.javadev.org/auth" xs="http://www.w3.org/2001/XMLSchema">
<element type="xs:string" name="username">
<element type="xs:string" name="password">
<element name="auth">
<complextype>
<sequence>
<element ref="auth:username">
<element ref="auth:password">
</sequence>
</complextype>
</element>
</schema>

Client applications send XML messages to the server in the defined format. This transition is done via the HTTP protocol but the way we use to do this transition varies:

JAX-WS : JAX-WS is a fundamental technology for developing SOAP based and RESTful Java Web services. JAX-WS is designed to take the place of JAX-RPC in Web services and Web applications. We use JAX-WS technology to send/receive XML messages to/from web services. In this approach XML messages are transferred as StreamSource objects and connection to the web service is done via javax.xml.ws.Service and by using Dispatches. This approach will be introduced in more details.
HttpURLConnection: another way to transfer messages between RESTful web services is using HttpURLConnection. In this approach the Web service is accessed with an HTTP GET request. The client application needs to issue the HTTP GET, and process the HTTP response stream that contains the XML document.

Depends on our requirements, we can use one of the approaches mentioned above.In this article we use JAX-WS API, however we will take a look at the other approach to find out differences.
Our example consists of two parts:
- Web Service: Web Service receives an XML document which needs to be authenticated and returns an XML message which indicates that the authentication was passed or failed.
- Client: Client is an application, It can be a simple java application, another web service or any other kind of application. Client is responsible for sending the authentication XML message and receiving the result XML message.