REST vs. SOAP - Java Tutorial and Comparison

Posted December 20, 2009

I had a discussion with my professor because the lecture on middleware covered SOAP but not REST.

In my opinion both have their strengths and weaknesses, but REST is way better in term of chaching. To prove that I implemented a simple server and client both with SOAP and RESTful HTTP. The results won't be very accurate but sufficient for comparing the magnitude of the performance. To make the comparison easier I used Java as programming language for both client and server.

SOAP

Implementing the Server

1. Download the latest version (2.2.5) of Apache CFX and untar it
2. Create a new Java project in Eclipse and add all JARs of Apaches CFX and its dependencies as referenced libraries.

3. Write the interface for the server (it's basically a book collection)

       @WebService
       public interface BookCollection {
           void addBook(Book book);
           Book getBook(int isbn);
           Book[] getAllBooks();
           void editBook(Book book);
           void deleteBook(int isbn);
       }
    

4. Write the data class

       public class Book {
           public int isbn;
           public String author;
           public String title;
       }
    

   You might want to encapsulate the fields. In Eclipse you can use the menu Source -> Generate Getters and Setters ...

5. Write the implementation

       @WebService(
           endpointInterface = "de.livoris.restvssoap.BookCollection",
           serviceName = "MyBooks")
       public class MyBookCollection implements BookCollection {
    
           private Map<Integer, Book> books = new HashMap<Integer, Book>();
    
           @Override
           public void addBook(Book book) {
               books.put(book.getIsbn(), book);
           }
    
           @Override
           public void deleteBook(int isbn) {
               books.remove(isbn);
           }
    
           @Override
           public void editBook(Book book) {
               Book old = getBook(book.getIsbn());
               old.setAuthor(book.getAthor());
               old.setTitle(book.getTitle());
           }
    
           @Override
           public Book[] getAllBooks() {
               return books.values().toArray(new Book[books.size()]);
           }
    
           @Override
           public Book getBook(int isbn) {
               return books.get(isbn);
           }
       }
    

6. Writing the actual SOAP-Server (better in a new Java project)

       public class Server {
           public static void main(String[] args) throws IOException {
               System.out.println("Starting Server");
               MyBookCollection myBooks = new MyBookCollection();
               String address = "http://localhost:9000/myBooks";
               Endpoint.publish(address, myBooks);
               System.in.read();
           }
       }
    

7. The WSDL of the SOAP service is now accessible through http://localhost:9000/myBooks?wsdl.

Implementing the Client

1. Apache CFX has a tool for generating a proxy from the WSDL. To generate the SOAP proxy for the book collection set the environment variables JAVA_HOME, CFX_HOME and PATH correctly, then type:

       mkdir -p BookSOAPClient/src
       wsdl2java -d BookSOAPClient/src http://localhost:9000/myBooks?wsdl
    

   You might want to rename the package afterwards.

2. Now you need a list of books. An easy way is to download this CSV file and to import it using the opencsv library and the following code:

       private List<Book> books = new LinkedList<Book>();
    
       public void importFromFile(String path) throws IOException {
           CSVReader reader = new CSVReader(new FileReader(path));
           String [] nextLine = reader.readNext(); // skip first line
           while ((nextLine = reader.readNext()) != null) {
               // Reject books with no or invalid ISBN
               if (nextLine[1].matches("[0-9]+")) {
                   Book b = new Book();
                   b.setAuthor(nextLine[0]);
                   b.setIsbn(Integer.parseInt(nextLine[1]));
                   b.setTitle(nextLine[2]);
                   books.add(b);
               }
           }
       }
    

3. Implement a dummy client that will add a book from the CSV file and then request all books until all books have been added.

       private BookCollection collection = MyBooks.getMyBookCollectionPort();
       private int adds = 0;
       private int gets = 0;
    
       public void work() {
           Book current;
           for (Book current : books) {
               collection.addBook(current); adds++;
               Book[] serverBooks = collection.getAllBooks(); gets++;
               for (Book b : serverBooks) {
                   collection.getBook(b.getIsbn()); gets++;
                 }
           }
       }
    

4. Run the main method, that will import the CSV data, start the dummy client and measure the execution time.

       public static void main(String[] args) throws IOException {
           Client client = new Client();
           client.importFromFile("etc/books.csv");
           long start = System.currentTimeMillis();
           client.work();
           long end = System.currentTimeMillis();
           System.out.println("Execution time = " + (end - start) + "ms");
       }
    

5. The result of running the client is shown below:

   Indicator	Value
   Add requests	78
   Get requests	3197
   Time	25742ms

Caching

SOAP always uses HTTP POST requests for each message, therefore its neccessary for the caching web service to read the whole HTTP request including its body, to open the provided SOAP envelope and to unmarshall the XML that describes the message. In the end responding with a cached response is not different from normal responding. If you use Apache Axis or ASP.NET then you can enable caching inside your service class but if you want to use a caching proxy the only SOAP webservice cache I found was Ventus Proxy.

REST

Implementing the Server

1. Add marshall and unmarshall methods to the Book class. For this example I use JSON with the Java library from json.org.

       public static Book fromJSON(JSONObject object) throws JSONException {
           Book result = new Book();
           result.setIsbn(object.getInt("isbn"));
           result.setAuthor(object.getString("author"));
           result.setTitle(object.getString("title"));
           return result;
       }
    
       public JSONObject toJSON() throws JSONException {
           JSONObject result = new JSONObject();
           result.put("isbn", getIsbn());
           result.put("author", getAuthor());
           result.put("title", getTitle());
           return result;
       }
    

2. The next step is to create a the actual Server with the Java library Restlet.

   To do this, you have to create two different resources. One for the book collection and one for a single book. The resource for the book collection supports adding books and getting all books.

       public class BookCollectionResource extends ServerResource {
    
           // the underlying book collection
           protected static BookCollection books = new MyBookCollection();
    
           @Post
           public void add(Representation entity) throws Exception {
               JsonRepresentation rep = new JsonRepresentation(entity);
               Book book = Book.fromJSON(rep.getJsonObject()); 
               books.addBook(book);
               setStatus(Status.SUCCESS_CREATED);
           }
    
           @Get
           public JsonRepresentation getAll(Representation entity) throws Exception {
               JSONArray jsonArray = new JSONArray();
               for (Book book : books.getAllBooks()) {
                   jsonArray.put(book.toJSON());
               }
               setStatus(Status.SUCCESS_OK);
               return new JsonRepresentation(jsonArray);
           }
       }
    

3. The resource for a single book uses the isbn parameter of the request to find the book and supports get, update and delete.

       public class BookResource extends ServerResource {
           // the underlying book object
           private Book book;
    
           @Override
           protected void doInit() throws ResourceException {
               super.doInit();
               setDimensions(new HashSet<Dimension>(Arrays.asList(Dimension.MEDIA_TYPE)));
               int isbn = Integer.parseInt(((String) getRequest().getAttributes().get("isbn")));
               book = BookCollectionResource.books.getBook(isbn);
           }
    
           @Get
           public JsonRepresentation getIt(Representation entity) throws Exception {
               if (book == null) {
                   setStatus(Status.CLIENT_ERROR_NOT_FOUND);
                   return new JsonRepresentation(new JSONObject());
               } else {
                   setStatus(Status.SUCCESS_OK);
                   JsonRepresentation rep = new JsonRepresentation(book.toJSON());
                   Calendar now = Calendar.getInstance();
                   now.add(Calendar.MINUTE, 30);
                   rep.setExpirationDate(now.getTime())); // assume that a book won't change very often
                   return rep;
               }
           }
    
           @Put
           public void storeBook(Representation entity) throws Exception {
               if (book == null) {
                   setStatus(Status.CLIENT_ERROR_NOT_FOUND);
                   return;
               }
               JsonRepresentation rep = new JsonRepresentation(entity);
               Book updated = Book.fromJSON(rep.getJsonObject()); 
               book.setTitle(updated.getTitle());
               book.setAuthor(updated.getAuthor());
           }
    
           @Delete
           public void deleteBook() {
               if (book == null) {
                   setStatus(Status.CLIENT_ERROR_NOT_FOUND);
               } else {
                   BookCollectionResource.books.deleteBook(book.getIsbn());
                   setStatus(Status.SUCCESS_NO_CONTENT);
               }
           }
       }
    

4. Finally the code to start the server is needed.

       public static void main(String[] args) throws Exception {
           Component component = new Component();
           component.getServers().add(Protocol.HTTP, 9001);
           component.getDefaultHost().attach("/books", BookCollectionResource.class);
           component.getDefaultHost().attach("/books/{isbn}", BookResource.class);
           component.getLogService().setEnabled(false);
           component.start();
       }
    

5. You can use your browser to access the books by navigating to http://localhost:9001/books.

Implementing the Client

1. You need to create a new Java Project and reference the Project with the Book and the BookCollection class, as well as Restlet and JSON jar files.

2. Create a class that implements the BookCollection interface and that uses the Restlet library and the methods toJSON and fromJSON of the Book class to create HTTP requests.

       public class BookCollectionProxy implements BookCollection {
    
           private static final String SERVICE_URL = "http://localhost:9001/books";
    
           ClientResource books = new ClientResource(SERVICE_URL);
    
           @Override
           public void addBook(Book book) {
               try {
                   Representation rep = new JsonRepresentation(book.toJSON());
                   books.post(rep);
               } catch (JSONException e) {
                   e.printStackTrace();
               }
           }
    
           @Override
           public void deleteBook(int isbn) {
               ClientResource res = new ClientResource(SERVICE_URL + "/" + isbn);
               res.delete();
           }
    
           @Override
           public void editBook(Book book) {
               try {
                   ClientResource res = new ClientResource(SERVICE_URL + "/" + book.getIsbn());
                   Representation rep = new JsonRepresentation(book.toJSON());
                   res.put(rep);
               } catch (JSONException e) {
                   e.printStackTrace();
               }
           }
    
           @Override
           public Book[] getAllBooks() {
               try {
                   JsonRepresentation json = new JsonRepresentation(books.get());
                   JSONArray array = json.getJsonArray();
                   Book[] result = new Book[array.length()];
                   for (int i = 0; i < array.length(); i++) {
                       result[i] = Book.fromJSON(array.getJSONObject(i));
                   }
                   return result;
               } catch (Exception e) {
                   printStackTrace();
               }
               return null;
           }
    
           @Override
           public Book getBook(int isbn) {
               try {
                   ClientResource res = new ClientResource(SERVICE_URL + "/" + isbn);
                   JsonRepresentation rep = new JsonRepresentation(res.get());
                   return Book.fromJSON(rep.getJsonObject());
               } catch (Exception e) {
                   e.printStackTrace();
                   return null;
               }
           }
       }
    

3. You can now use the client with the dummy client as shown above with REST.

   Indicator	Value
   Add requests	78
   Get requests	3159
   Time	23873ms

Caching

Because a REST request is nothing more then a normal HTTP request, every caching HTTP proxy can be used to improve the performance. In the example I use Apache HTTP Server.

1. The first step is to install Apache. If you use linux then apache2 will propably be in a package repository, otherwise you might download the source from the official website or a distribution like XAMPP.

2. Configure apache2 to act as an caching proxy.

   The following configuration create a virtual host, that will serve at http://localhost:9002/ and will forward request that are not cached to http://localhost:9001/.

       Listen 9002
    
       <VirtualHost *:9002>
           Servername localhost
    
           Location /
               Order allow,deny
               Allow from all
           /Location
    
           ProxyRequests Off
    
           ProxyPass / http://localhost:9001/
           ProxyPassReverse / http://localhost:9001/
    
           # Enable memory caching
           CacheEnable mem http://localhost:9001/books
    
           # Limit the size of the cache to 16 Megabyte
           MCacheSize 16384
       </VirtualHost>
    

3. After changing the SERVICE_URL in the BookCollectionProxy to http://localhost:9002/books all request go through the Apache HTTP Server that will automatically cache some of the books and returning their JSON representation without even contacting the Restlet Server. This speeds up the processing as shown in the table below.

   Indicator	Value
   Add requests	78
   Get requests	3159
   Time	16632ms

Results

In both examples Jetty (a small embeddable web server) was used and not a full blown application server like Tomcat that would probably be much faster. Comparing the three solutions SOAP, REST and REST-Caching the last one has by far the best performance. And that is exactly why I think REST is a very good solution for scalable web applications even though REST has disadvantages because it is very restricted and therefore sometimes hard to use for a general purpose interface.