I'm the author of RESTful Java Web Services. The book is now available online or your local bookstore (I think).

This book is a guide to develop RESTful web services using Java and the most popular RESTful frameworks available today. I cover the theory of REST. I cover practical coding examples of RESTful clients. I outline the RESTful design process--yes, it's different from traditional web application development. Finally, I implement a full social networking web service that adheres to all the REST constraints Fielding outlines in his thesis. I cover the following frameworks: Jersey's JAX-RS, Restlet's Lightweight REST, JBoss's JAX-RS RESTEasy, and Struts 2 + REST Plugin. The same RESTful web service; 4 different implementations.

If you are new to RESTful Java web services, if you are already familiar with REST theory and want to use the Java technology stack to create robust web services, if you want practical Java coding examples, this is the book for you.

At first sight, it's hard to think of why a noun-based request is better than a verb-base request. Let me introduce one simple change to our services and you'll see a couple of things changing. Let's change the implementation of the services from JSP to ASP. The REST request doesn't change; the RCP call changes its action based calls from <action>.jsp to <action>.asp. With this change, we've potentially broken user bookmarks, and we've affected any caching along the request chain.

7:49 PM
I wrote earlier about pleasing editors and readers. I think that's the wrong way to approach things. I think I have to please me first; if I'm enjoying the process--and I am--the work will speak for itself. At least this is the way I feel about everything I do: if I'm having fun, the rest comes easy.

Nevertheless, understanding the reader is rule #1 for any writer. I'm writing this book from an objective point of view: if I were looking for information on RESTful Java web services, would I read this title? I would read this book. Do I understand my audience? I'm a developer, and I kind of understand me...So I understand a bit about other developers. What's more, I can talk shop with them--that's always a plus. Of course, we come in different shapes and sizes. The unifying characteristic, though, is the desire to create great applications: I know most developers want to create great software.

March 1, 2009
6:02 PM
Yesterday and today, I've been having a great email exchange about my post above, where I mention a minor difference between modern web applications and legacy web applications.

I think the word legacy is too strong to describe the way we build web application: with only GET and POST methods. The design and architecture of these application works, so a fair question is why change to a REST style and work within the constraints of REST.

Depending on who you talk to, you can get the preachy argument that all your new web applications should be RESTful. I agree, not because I'm a blind follower of REST-like architectural design but because it makes sense to rethink our mode of thinking--specially, when the new wave of thinking makes our applications better and easier to maintain. REST offers that, because of constraints and because the communication protocols are the web itself (TCP/IP, HTTP, etc.).

Of course, the exchange led to more discussion, but it's great to hear from a fellow author. I haven't read his book, but I will make a point of it now.

March 2, 2009
3:10 PM
I just completed draft v.0.0.1 of Chapter 1. I have some fact checking to do and modify a couple of diagrams, but I think this is it for now. I have to send it to the editors by the end of the week, so I still have a couple of days to play with the content.

Next steps: wait and see how much the editors will want to change and then change it; and, I guess, I have the next 10 chapters to write. However, Ch1 is likely to be the most writting intensive part of the book: lots of examples and running code to come.

March 3, 2009
5:26 PM
Truman Capote wrote, "I believe more in the scissors than I do in the pencil." This is one of the old cliches about writing. We don't use scissors or pencils anymore--at least I don't--but cutting from a draft is a must...and it's a hard.

6:22 PM
I find the writing process similar to the drawing process; and I find the drawing process similar to the coding process. Perhaps I have this view because of my lack of experience in all of them. There is something mechanical and instinctive in all these crafts (yes, coding is craft and art and science and engineering all rolled into one). We must follow rules in all 3; however, rules alone don't make a great book, a great drawing, or a great program. The result of all 3 is something that begins simply and ends complex.

I wish I knew more about music. How are any of these like playing music? And I only wonder how playing music compares to writing, drawing, or coding. I don't wonder about composing, because, I think, it's similar to writing, drawing, or coding.

March 5, 2009
1:29 AM
v0.0.3 of Chapter 1 is done. It's close to finished now: I've modified the diagrams I needed to modify and refined the main sections that needed work. Later on today, I will rewrite the introduction and summary.

7:09 PM
I've been reading Stephen King's book On Writing. Although the book is about writing fiction, it applies to any kind of writing, as every story has a narrative and if told truthfully, it will have an impact on someone.

I've never read anything he's written, until now. I've watched movies based on his books, but I don't consider his books classics or must reads. Nevertheless, he's a very successful writer: he sells a lot of books, so he must be doing something right.

Part of On Writing is autobiographical, and the book has a self-deprecating style to it. King is a plain but fluid writer. He's a complete opposite of Conrad Black; Black comes out as pedantic in every sentence he writes. I'm reading his FDR biography and it's not a bad book, but I had to buy a dictionary to follow him. Just because the English language has many adjectives, it doesn't mean that he has to use all of them in almost every page.

I can't say at this point if I'll ever buy any more of King's books (although I'll buy Black's next book, likely to be about imprisonment). I'm not into fiction. And if I read fiction, I prefer to read the so called classics. In fact, I have some rules about reading; silly as they are, they go as follows:

Rule 1: If the author is dead and considered a genius, I will read his or her fiction literature (Tolstoy, Kafka, et al.).

Rule 2: If the author is not dead, the book has to be non-fiction and specific about only one subject (for example, software engineering, genetics, biographies, history, etc.). The majority of these books fall under technical subjects, though.

Rule 3: If Oprah is pimping it, I will not read it.

Sorry, Anna Karenina--I know this title contradicts Rule 1, but Rule 3 has more weight (maybe some day I'll pick it up; Tolstoy is a great writer--or at least it appears so from the current translations of his work).

Rule 4: If the book is the new meme (Wikinomics, The World is Flat, Programming the Universe, etc.), I'll consider it but I first need to screen the author--the author's ethos plays a big part here. It's also likely that these books are in the best sellers list of the New York Times; however, making the list doesn't make me to want to read the book any more or any less--it's all about the author, at this point.

Rule 5: I don't read for dummies titles. I tried once, but I don't see the point of them.

Rule 6: Break rules 1, 2, or 4 only in exceptional cases. For example, I read Dan Simmons Ilium and Olympos 3 summers ago (Ilium was better). I've also read The Curious Incident of the Dog in the Night-time (meh).

Rule 7: I'll read Spanish writers who are alive, only if they have won the Nobel prize for literature (there's only so much "magical realism" a person can take). As a rule, I read the Spanish version first and then the English version (to see if I've missed anything).

As a teenager, I had to read other Spanish writers but I didn't like their books: maybe because I was forced to read them for exams (although my Letras--the English equivalent in Latin America--high school teacher en el Nacional was very good: thanks Rudy Menjivar, wherever you are).

Now, am I forgoing great current authors? Probably, but there are a lot books that fall under the umbrella of these rules. What's more, if any of their books are really good they will become classics eventually--I'll read them then.

March 6, 2009
7:36 PM
I just realized that I have no more highlighted text in my working document for the first chapter. This means that Chapter 1 is ready for its first round of editorial reviews. This also means that after I re-read it and email it, I would have reached my first milestone--and right on schedule, nonetheless.

According to my contract and my plan, I'm to complete a chapter roughly every 3 weeks. I'm taking 2 days off from writing, but I already have Chapter 2 mapped in my head. Actually, I already have the whole story mapped in my head. The challenge, as with every writing exercise, is to bring the details into a coherent chain of paragraphs.

I think you could say that today is a big day for me. I'm always surprised how the big days in our lives are so unceremoniously normal. Aren't you?

I always remember the last day of class on most of the schools I went to: they were over with a whimper and not the proverbial big bang playing in my head. No "good luck with the rest of your life" from the professors (how would they know that it's the last day for any of the students); not one "I hope I made a difference in your studies" (perhaps it would be pretentious for teachers to think they made a difference; however, some do make a difference, for better or for worst). I guess normal life is just...normal. And completed chapter or not, life goes on. Which reminds me, I should go eat dinner now.

March 7, 2009
1:23 AM
I'm sure most of you know this, but it's an invaluable step to print the actual document to proof read the hard copy. It elevates the work to a new level. Editiing took me longer than I had anticipated. Nevertheless, I've just emailed the first draft of chapter 1, so I'm now officially off for 2 days.

March 9, 2009
5:00 PM
I didn't think I could go for 2 days without doing anything, but I was able to just relax, visit friends, and read a little.

Chapter 2 has began, with "2" as the first keystroke of this chapter. I'm breaking down accessing RESTful web services in 2 parts. In the first part I cover the details of creating different types of clients; and in the second part I cover more interesting examples--the ones that do real stuff with web services. There is definitely less writing for this chapter, but there is likely to be as much research needed as the first.

I want to make some snippets of Chapter 1 available, but I don't know what the rules are. If it's allowed by the publisher, I'll put some PDFs files in this page.

6:52 PM
I'm a great believer of creation by osmosis; well, there isn't much to believe, actually--nature works this way. Thus, it's unlikely I will write anything this week; however, I will spend most of my time on research and a few coding samples.

March 12, 2009
2:18 PM
Research is going well. Lots of examples to choose from. I haven't made up my mind as to what RESTful service to use for Ch2, but I'm close to making a decision, as I have the main story now. What I know is that all my development will be done within the Eclipse IDE. Furthermore, I making all the code available for download once the book is published.

I bought the domain name restfuljava.com and will start updating it shortly. Perhaps I will move this journal over; I'm not sure yet.

3:30 PM
I keep replacing this page with an empty one, because I'm not too comfortable writing so much personal information on the web just yet, even though I've been blogging for more than 5 years now and I've been using the internet since 1990 when I discovered I could connect to the University of Waterloo's library via modem (I used gopher, Mosaic, and ftped 32 1.4 MB diskettes to build Linux to install in my PC, used PINE, and my favorite editor is vi).

I find blogging self-serving and embarrassing, but it's good for marketing. I believe, however, that all these technologies we use are not just to sell things or dupe us into buying things we don't need; we can use them to connect with peers and exchange valuable information (and I'm not talking about Facebook). For example, all the contract work I'm engaged in comes directly from this web site and my company's site. I don't foresee this changing; on the contrary, my network of contacts increases daily and my outreach now covers the entire world: I have had paying engagement in the US and Canada, and the publisher for my first book is from the UK. What's more, I exchange emails about my coding samples with people from India, China, and South America. I never imagined I could ever do this, let alone, just sitting at home or from coffee shops around town (I'm writing this right now at the Starbucks inside Chapters, in Waterloo). To say that we live in a great age is an understatement.

For now, I've decided to keep the journal going and making it public. To what purpose? None other than I like writing. I'm not sure who else reads it, but here it is and it will be.

Note that even though I'm in the middle of writing, I'm still available for development projects: web applications and desktop networked applications.

March 21, 2009
5:26 PM
Most of the RESTful development we do is consumming results. On that note, this is the smallest Java RESTful client you will see today:

/*
 * RESTClient.java - Mar 17, 2009
 *
 * Copyright (c) 2009 Jose Sandoval
 * 
 * All rights reserved.
 */
package com.restfuljava.chapter2.command;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.net.MalformedURLException;
import java.net.URL;
import java.net.URLConnection;

public class RESTClient {

	/**
	 * Connect to twitter REST API and get public messages.
	 * 
	 * @param args
	 */
	public static void main(String[] args) {
		try {
			URL twitter = new URL("http://twitter.com/statuses/public_timeline.xml");
			URLConnection tc = twitter.openConnection();
			BufferedReader in = new BufferedReader(new InputStreamReader(tc.getInputStream()));
			String line;

			while ((line = in.readLine()) != null) {
				System.out.println(line);
			}
		    
			in.close();
		} catch (MalformedURLException e) {
			e.printStackTrace();
		} catch (IOException e) {
			e.printStackTrace();
		}
	}
}
	  
	  

<?xml version="1.0" encoding="UTF-8"?>
<statuses type="array">
    <status>
      <created_at>Sat Mar 21 21:29:08 +0000 2009</created_at>
      <id>1367587475</id>
      <text>@SDMSTYLECEO hey girl I'm at this restaurant boycotting eating this baby cow parmesan. Lmao</text>
      <source>&lt;a href=&quot;http://orangatame.com/products/twitterberry/&quot;&gt;TwitterBerry&lt;/a&gt;</source>
      <truncated>false</truncated>
      <in_reply_to_status_id />
      <in_reply_to_user_id>16535504</in_reply_to_user_id>
      <favorited>false</favorited>
      <user>
      <id>19477616</id>
      <name>J Starr</name>
      <screen_name>whoisjstarr</screen_name>
      <description> Editorial Director, Writer/ decision maker/ super dope chick who does lots of super dope things! 
 Swagger, Spandex, &amp;amp; Semicolons!  Cheeah! </description>
      <location>NY</location>
      <profile_image_url>http://s3.amazonaws.com/twitter_production/profile_images/104527501/
                          iheart_biggerme_normal.JPG</profile_image_url>
      <url></url>
      <protected>false</protected>
      <followers_count>181</followers_count>
    </user>
    </status>
	
	...
	
    </statuses>

There is nothing much to add here: it's just a client consumming a RESTful result.

March 24, 2009
4:51 PM
I think all developers should code APIs and not just code programs. This mode of thinking forces us to look at a solution as a reusable chunk of logic and not just as a once-of set of statements.

I'm envisioning the examples in Chapter 2 to not only be simple exercises, but also to become a stand alone testing library for the rest of the book. I'm 1/3 of the way there.

March 26, 2009
1:39 PM
Chapter 1 is back from the editors. There are no major changes required: just a couple of words missing here and there, and I need to change number references to letters (instead of 2 it should be 'two'). I still want to make a few edits on my own, but it's looking good.

March 31, 2009
12:36 AM
Chapter 2 is ready for my final review. I'm happy with the length and all the programs. Now to sleep a little, then pay my company's taxes, and finally edit the manuscript. Busy day ahead.

April 2, 2009
1:14 PM
I completed Chapter 2 a couple of days ago. It took a few days longer than I expected.

After taking a day off from the whole writing gig, I want to shorten one of the coding samples. There is nothing wrong with it, but I think it may be too long for anyone to type off the book. I'll wait and see what the the editor(s) think.

And just like that, I begin with Chapter 3.

April 12, 2009
6:54 PM
I coded mashup of a semantic app that searches google, yahoo, and twitter. It's a small application, but it illustrates how publicly available APIs are used to create interesting things.

Chapter 3 is a short chapter, but I think it is useful. And all the code will be available in the book and this site.

Interesting fact: book titles are not protected by copyright laws. For example, I can write a book with the title "War and Peace" and it would be OK.

April 14, 2009
11:47 PM
I like to keep track of my draft revisions, so that I can study and improve my writing process. It's a good thing I do this.

Today, I Crtl-X a large section of text that I intended to move to a different location in the chapter, but I forgot I had the content in the clipboard and continued to edit other parts of the text. I finally remembered that I had removed the section when I looked for a reference. I have to tell you, I panicked. When I finally caught my breath, I looked for the version number I was editing and I just opened the previous version and Ctrl-C/Ctrl-V the content back into the right place.

Why am I not using a repository? I thought about using one, but I don't want to have anything dangling anywhere. I feel safer if I keep everything self-contained in my laptop and my external backups.

Moral of the story: backups are your friend.

April 28, 2009
7:42 PM
I had to edit Ch2 and Ch3. Nothing major, but I think they are better now. For Ch4, I design a full web service. In the next few chapters I have a lot more coding to do.

May 13, 2009
11:34 PM
Things are going well. Chapters 2 and 3 have been accepted, and editors reviewed Chapter 4 last week and have suggested some additions--a few more introductory sentences here and there.

Chapter 4 is the bridge between theory and practice. The RESTful design process has a few different ways of looking at things. For example, everything is based on resources and there is no need to figure out what happens to this resources, because you already know what happens: you use the HTTP protocol methods to exchange resources in the form of representations.

This week, I'm trying to write two chapters at once--I want to catch up with the original schedule. Though, I'm only 1 week behind, which is not too bad. However, I'm still working through the code: I actually have to implement the same web service in 3 different RESTful frameworks, i.e., lots of design work and many lines of code.

May 28, 2009
8:08 PM
A couple of weeks ago, I said that wanted to write 2 chapters at once. That was a no go: I managed to write only Chapter 5. Ch5 is the longest chapter so far. It's around 40 pages, but I cover a great deal of the Jersey framework, and I managed to explain a full implementation of a non-trivial RESTful web service. Further, I managed to separate the code into layers and I now have 2-thirds of the code I need for all the other framework I'm covering.

For Chapter 6, I'm write about the Restlet framework. There are 2 versions of it, so I'm debating if I should cover both of them or just the latest. I'm opting for both, but we'll see.

Once I complete Chapter 6 (in the next 2 weeks), I'll be half way through the book.

June 8, 2009
2:22 PM
For Chapter 6, I finally decided to cover Restlet versions 1.1 and 2.0. The chapter is longer, but it's fairly comprehensive because of it. My thinking is that if you buy the book because you want to migrate an existing version 1.1 web service to the new and improved version 2.0, then you'll be covered, for you'll know where the differences between each version are. On the other hand, if you buy the book to start developing web services using either 1.1 or 2.0, then you'll also be covered because I go through everything you need to know to create a full RESTful web service from scratch.

Note that this book is not only about Restlet. This book is about RESTful Java Web Services. I cover the most popular RESTful Java frameworks today. For example, in Chapter 5, I cover Jersey, the JAX-RS implementation. So if you decide that Restlet doesn't do everything you need, you can play around with the code and compare between them. The advantage of my approach for this book is that I implement same requirements for multiple frameworks: the code does exactly the same, but using different REST architectures. Chapter 1, of course, covers the theory of REST, but this is a developer's title full of examples and working code.

In general, the architecture of a web service doesn't change regardless of the framework you use; however, there are a few subtleties that could give you some grief if you don't know where to look. I've tried to cover all those subtleties in my book. What's more, because of how I've broken down the implementation code, you will be able to compare between RESTful frameworks and then be able to decide which approach works best in your case.

I'm a great believer of just enough documentation to be productive quickly. For each chapter, where required, I include architectural diagrams before any code is written. This is the architecture for Chapter 6 (and for all frameworks, really, as I just swap the web layer with the desired RESTful framework and I'm done):



Yes, for each framework (Jersey, Reslet 1.1 and 2.0, RESTEasy), I implement the same web service that I defined in Chapter 4. And, for the same price of the book, all the source code is included in the book and will be available for download. Shameful plug; and, yes, I'm wearing that kind of sweater. Take your pick:


I think this entry (or part of it) will become the introduction to the book.

June 11, 2009
12:32 AM
I just shipped Ch6 to the editorial group. I like Chapter 6, just as much as like all the other chapters so far. :)

I'm taking 2 days off from writing. I find this decompression time good for my brain cells to recover. I also get some time to read other things.

June 16, 2009
2:24 PM
I began research for Chapter 7 sometime ago, but it's only today that I delve deeper into the content and only today that I begin writing.

June 29, 2009
3:19 PM
As the work progresses, I've realized that a couple of chapters need reordering. What was Ch8 is now Ch7 and Ch7 is now Ch8.

I need 4 more chapters to complete the book. I had planned for 11 chapters, but the content of chapters 9 and 10 are closely related; therefore, I want to combine them into 1 and make the total number of chapters 10.

Now back to regular programming...that is completing Ch8. So close, I can already smell the ink and paper.

An interesting note: I like bookstores because I like the smell of paper. I'm partial to the books inside the store; for all I know, they are just empty shells of perfectly good paper.

July 21, 2009
3:22 PM
The editor and I decided to keep the original number of chapters. The comment I got was that longer chapters are not well received by readers. I can understand that. So everything stays as I originally planned. This surprises me, as I thought I would be changing things mid way. So far, I've stayed within the boundaries of the original outline.

On a side note, I'm not really counting the number pages as I write, but somehow end up right of the money: without looking, I reach the page limit as I complete the content.

Chapter 8 is now complete. I need to edit it, but everything I wan to say is already there. I actually want to say more about Struts 2 and the REST plug-in, though I won't in the book because that would be editorializing--that's a big no-no. The book does have my point of view; however, I don't want to make recommendations in it. The book itself is an exploration of web services implementation using Java technologies. I have covered 4 frameworks (Jersey, Restlet, RESTEasy, and Struts 2 + REST plug-in), so I think the reader will have a good idea of what framework is the most suitable for a specific problem.

Compared to the other frameworks I cover, the Struts 2 REST plug-in has a long way to go. For example, it follows the Ruby on Rails style of REST, which is too web-browser centric. This is a minor deficiency in the plug-in, because it can't handle the HTTP Accept header for content negotiation. However, I cover a way to still make use of the framework and proper content negotiation using the HTTP Accept header (I'm writing a blog entry about it, and will post the example).

A bigger problem with the framework, however, is the lack of support for hierarchical URIs and multiple-variabled URIs. For example, you can't implement a service that would require URIs similar to these: /myservice/hiearchy1/hiearchy2/{identifier} or /myservice/{identifier1}/{identifier2}/{identifier3}. I don't understand why it's not supported, so I hope this problem is remedied for the sake of competition with the other frameworks.

Having looked at all the major RESTful frameworks available today, I wouldn't recommend the Struts 2 REST plug-in unless you are required to use it. In other words, if you must have Struts 2 and REST, then it's a moderately good choice. And even if you must have Struts 2 as your web layer, you can use Jersey or RESTEasy with your existing Struts 2 application. The problem with the state of the plug-in is that you need to work around too many of its limitations, specially when there alternatives available that just work out of the box.

July 23, 2009
2:36 AM
The importance of a familiar user interface.

July 24, 2009
3:07 PM
I completed editing Chapter 8 yesterday. I have 3 more to go, with 3-4 weeks to complete them. The last 3 chapters are not that long, but I still need to research a few topics.

August 17, 2009
7:29 PM
I'm back from a long vacation and plan to complete the last 3 chapters in the next 2 weeks. I'm eating up the little flexibility I had in the schedule, but the time off served me well.

I've been working or writing for a long stretch, so decompressing from all the coding and writing was a welcomed change. The problem now is that I feel like I need a vacation from my vacation: I ran too much and swam too much and I feel like I need some time off any physical activity (no running or weight training for this week). On the plus side, I decided to return to swimming more regularly: I always liked swimming, and I have come up with a great swimming training schedule.

August 20, 2009
12:15 PM
More options for RESTful clients...

August 28, 2009
3:39 PM
I finished the first draft of RESTful Java Web Services yesterday night. I had planned for 11 chapters, but I removed Chapter 10 at the last minute, so now the total number of chapters is 10. I may end up publishing the removed chapter as a blog post.

Final edits begin...in a couple of days. I need sometime off and I need to spend some time coding for a project I'm currently working on.

September 26, 2009
10:20 PM
I'm in middle of final edits for the last few chapters. The technical reviewers have been and continue to be of great help. The publishing date approaches.

October 28, 2009
11:32 PM
The book is in the final phase of publishing. It will be available on November 4, 2009.

November 4, 2009
11:00 AM
The book went to the printers today. We made it right on time: not a day late. Thanks to technical reviewers and the entire Packt team for all their work. I had a lot of fun writing this book. If you buy it, I hope you find it useful.

For any questions, you can email me at jose@josesandoval.com.