SOA, Web Services, and RESTful Systems

Building RESTful Systems

If you eliminate typical web-service protocols (XML-RPC SOAP, WSDL, and so on), then how do you build an SOA-based RESTful system? With REST, you use that same mechanism used to request a web page—the HTTP query URL. For instance, the sample SOAP call in Example 1 makes a request for an employee's benefits information from a human resources web service.

<SOAP-ENV:Envelope xmlns:SOAP
 ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header> 
        some data here...    
    </SOAP-ENV:Header> 
    <SOAP-ENV:Body>
    <GetBenefits>
        <user>123-45-6789</user> 
        <type>full_time_employee</type> 
    </GetBenefits>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

With REST, you simply replace a SOAP call, such as Example 1, with the URL http://humanresources.com/benefits?user=<USER_SSID>&type=full_time_employee.

The HTTP query URL definition is all you need to know and use to make calls to a RESTful service. The response can be HTML, comma-delimited data, XML, or a more sophisticated document type (such as a spreadsheet). Some claim that the return of anything but hypermedia-based content is not truly RESTful. However, as long as the system stays true to the REST principals for the request and the communication protocol, the response type is unimportant.

When you build a web application with a Java Servlet, for example, it's straightforward to read the data passed through URL query parameters, and to return any text-based response to the caller. The Java Servlet doPost method implementation in Listing One illustrates this. Here, the parameters used in the query in Example 1 are read and used to retrieve a user's employee benefits. The results are encoded as human-readable text. Because this is an example of a RESTful service, the request can be initiated—and the response viewed—by web browsers, or any component in a distributed application.

protected void doPost( HttpServletRequest req, HttpServletResponse resp)
  throws ServletException, IOException
{
    ServletOutputStream out = resp.getOutputStream();
    String response;

    String userSSID = req.getParameter("user");
    String userType = req.getParameter("type");
    if ( userType.equals("full_time_employee")) {
        Employee emp = lookupUser(userSSID);
        String medPlan = emp.getMedicalPlan();
        String dntPlan = emp.getDentalPlan();
        String retPlan = emp.getRetirementPlan();
        Response = "User " + emp.getFullName() +
                   " has medical plan: " + medPlan +
                   ", and dental plan: " + dntPlan +
                   ", and retirement plan: " + retPlan;
    }
    else {
        // ...
    }
    // Output the response from the worker
    out.println(response);
}