What do I need to start developing REST apps ?

Hola.
In order to develop SOAP web services, we have to use some kind of engines like AXIS in addition with some Java API for web services.
What do we need to develop REST web services ?
Thanks for your time.

John,

Right now the best choice for Java is the Restlet framework
(http://www.restlet.org/).

I have heard that JAX-WS 2.0 can expose RESTful services, but I
haven't really investigated it.

For what its worth there is a example of implementing a web service using the REST features of JAX-WS at Publishing a RESTful Web Service with JAX-WS.

To my mind the example isn't RESTful however.

I'm having a hard time swallowing that either
http://localhost:8080/jaxws-restful/addnumbers/num1/10/num2/20
or
http://localhost:8080/jaxws-restful/addnumbers?num1=10&num2=20
are addresses to resources with a representation of
<ns:addNumbersResponse xmlns:ns="http://java.duke.org"> <ns:return>30</ns:return> </ns:addNumbersResponse>

As far as I am concerned they deployed a (rather tiny) service at
http://localhost:8080/jaxws-restful/addnumbers
that processes the remaining path info (or query string) and returns a result.
So in my opinion it isn't a representative example of a REST web service.

Considering the source of the example I have to wonder whether the JAX-WS REST extension can be used effectively to implement a truly RESTful design.

That's a lot of work without much to show for it, but the result is RESTful.
The difference between non-RESTful and RESTful here is the difference between "add" and "GET". Addition has become a noun: the result of addition. It's really just an implementation detail what the URI and the behind-the-scenes code look like.

"A very tiny service" is one good description of a resource. And when you have an infinite number of them, you have a service that's a little larger.

Originally posted by Leonard Richardson:
Addition has become a noun: the result of addition.

Isn't there an anti-pattern emerging here? "Lets turn all our methods (verbs) into nouns - then we'll be RESTful" - ultimately giving license to avoid doing a "resource oriented design". Ever since the emergence of REST web services I liked it as a concept for a machine readable web (good-bye to HTML scraping). However I always found the definitions of what a resource actually is rather vague, more slippery than a wet piece of ice. How do you identify resources when you design your ROA? Ultimately the "turn your nouns into objects and the methods should be verbs" step is only a small step towards an effective object-oriented design. Why should resource-oriented design be any different? There has got to be more to it than "resource=noun", "[GET,PUT,POST,DELETE]=verbs". What am I missing here?

How some frameworks like JBoss Seam support REST ?
AFAIK, Seam is not using RESTlet API.
Thanks for your time.

John, I don't know for sure the answer to your question, but you will
probably have to wait for the JAX-RS standard (JSR 311).

Peer, "resource" is a deliberately vague term, about as vague as
"object". _Architecture of the World Wide Web_ (which I highly
recommend) says, "A resource should be assigned a URI if a third party
might reasonably want to link to it, make or refute assertions about
it, retrieve or cache a representation of it, include all or part of
it by reference into another representation, annotate it, or perform
other operations on it."

The uniform interface constraint only works because "resource" is so
vague. Many times when doing design I've run into a uniform interface
violation, and my eventual solution has been to expose some more
abstract thing, like a relationship, as its own resource. Much of what
I do in resource design is subconscious (the rest is described in
chapters 5 and 6), but I'm pretty sure that most of the normal rules
of object-oriented design apply. It's just that you have to apply them
under a very tight constraint.

It's _really_ hard to not end up with resources when you're making a
read-only dataset available through GET. Even if you deliberately try
for the RPC style, all you've done is create ugly URIs. From the
client's perspective it doesn't matter what the service designer
thinks: there's a fundamental congruence between the verb a RESTful
client sees (GET) and the verb the designer sees. Every GET request
runs some algorithm, whether the algorithm is addition or streaming
data from a file. But so long as the algorithm has no substantial side
effects, GET is appropriate and the URI can be seen as designating an
object.

The real test comes when the client needs to modify the dataset. Now
it does matter what the service designer thinks. If the designer truly
thinks of their resources as nouns, they'll decide it's time to break
out some of the other HTTP verbs and apply them to those nouns. But if
they're just following a "turn all the methods into nouns"
antipattern, they'll decide it's time to turn more methods into
nouns. This is how you get the Flickr URIs like
?methods=flickr.photos.delete exposed through GET. Now it's obvious
from an object-oriented standpoint (not just a URI ugliness
standpoint) that the Flickr designers didn't think of photos as
objects.

Anyway, I hope this helps.

Originally posted by Leonard Richardson:
John,
Right now the best choice for Java is the Restlet framework
(http://www.restlet.org/).

I find this intriguing. I took a look at the restlet framework but it seems very complex for a simple idea such as REST. What I find particularly strange is that it runs counter to the trend of building applications out of POJO (Plain Old Java Object) components, apparently requiring lots of code which needs to reference classes from the framework, and thus limiting the ability to unit test handlers in isolation.

I do quite a lot of developing REST style services, and I tend to use Mojasef. The Mojasef approach is to implicitly map each REST URL (or, at least, the bit before the query parameters) to a public method on some POJO.


A "hello world" application could be as simple as:

1. create a basic POJO such as:

package com.example; class Whatever { public String hello() { return "Hello, World"; } }

2. add an object of that class to the server context, in the simplest case by adding the following line to a config file:

http.application$=com.example.Whatever

When the server is started, an HTTP GET request to http://server/hello will return "Hello, World".

If we wanted to add some behaviour to another URL (say, http://server/goodbye ), it's just a matter of adding another public method to the application class. Private and protected methods are not exposed to the web, so developers are free to unit test and refactor however they desire.

There are, of course, ways of mapping a tree of such objects, ways of distinguishing between GET, PUT, POST, DELETE etc, and ways of accessing other request-related data such as query parameters and PUT/POST body.

I'd love to find out what Restlet has to offer that this approach lacks.
[ June 14, 2007: Message edited by: Frank Carver ]

Frank, I've been recommending Restlet because it's the only Java
framework I know of that's designed around REST. Its complexity stems
partly from the fact that it implements the whole REST dissertation,
not just its application to web services. There's certainly a market
for a simpler framework geared towards services.

Mojasef's architecture is a lot simpler, but the examples on the web
don't convince me that it's designed for read-write RESTful
services. Notably, the examples show a class variable (_n_, the visit
counter) changing in response to a GET request.

Now, something like a visit counter is fine as a side effect for GET,
because nobody makes a GET request just to bump up the visit
counter. But that example encourages the programmer to expose write
operations through GET, the way the Flickr and del.icio.us web
services do. The release notes also mention sessions, which violate
the principle of statelessness.

Looking at the example code I see a generic POST handler, which is the
kind of thing I'd expect to see if Mojasef made the programmer define
resources. But I'm not convinced that Mojasef is for RESTful
applications as opposed to REST-RPC hybrids like the Flickr API. I
could be wrong, and even if it's designed for hybrids you should be
able to use it RESTfully.

Why developing REST application requires a new API ?
Why Servlet API can be used ?
After all (AFAIU U == understand), REST based on GET requests.

Leonard,

Thank You for your clarification on the "resource" issue. Seems it's one of those things where you'll learn to recognize it once you work with it. I just figured that there are some qualities to resources that are a necessary basis for a good ROA. Maybe your book will help fill in the blanks a bit more about what the characteristics of a good ROA design are.

John, RESTful web services use GET requests only for read-only
operations on objects. For write operations they use POST, PUT, or
DELETE requests on the same objects. You can think of a RESTful system
as exposing a large number of objects, each of which can only respond
to four methods.

The Servlet API should be usable to build RESTful systems, but it's
not designed for RESTful systems. It's designed for traditional web
applications. I remember when I was writing servlets we had a separate
servlet class for each action. In a RESTful design I'd write a
separate class for each kind of object in the system.

Originally posted by Leonard Richardson:
Looking at the example code I see a generic POST handler, which is the
kind of thing I'd expect to see if Mojasef made the programmer define
resources. But I'm not convinced that Mojasef is for RESTful
applications as opposed to REST-RPC hybrids like the Flickr API. I
could be wrong, and even if it's designed for hybrids you should be
able to use it RESTfully.

In many ways I agree with you, but that's largely because of the way Mojasef arose. Originally the "itch" it scratched was the complexity and un-testability of code developed using close-coupled and overcomplicated frameworks such as the servlet API, JSP and Struts. With that in mind, the examples in the tutorial were aimed at demonstrating the advantages of Mojasef over that style of development.

At the time I was not really aware of REST, but over the last year or two have implemented several REST-based applications using Mojasef. I have also continued to develop Mojasef (and several associated sub-projects such as my Stringtree JSON reader/writer). The Mojasef web site is becoming a little dated.

Currently I'm developing a REST interface between loosely coupled customer-specific web "portals" and a sophisticated multiple media content repository. We are planning to roll out the first crop of portals soon, and encourage third-parties to develop their own portals to the same interface.

The previous portal interface, largely designed before I joined the company, used an ad-hoc minxture of SOAP-RPC and FTP. The REST approach is massively more scaleable.

I guess my point is that if a framework makes attaching objects to URLs simple, then it is likely to make coding REST simple, too. I still worry a little that RESTlet still does not make coding REST applications as simple as it might.

Ah, I didn't know you were responsible for Mojasef. I thought you were
just a user.

IMO the two most helpful features of a REST framework are attaching
objects to URLs and exposing the uniform interface methods as
native-language methods. Restlet does both (and a whole lot more).
I don't disagree that there's room in the ecosystem for a simpler framework.

I am new to both the Restlet and Mojasef framework.

I'd like to know if either of them support:
1. Auto generation of HTML documentations on the REST APIs registered (With info such as URL, HTTP METHOD, Query String, sample post xml request, sample xml response)

2. Versioning, backward compatibility support of REST APIs.

Thanks
-Victor

The Servlet API should be usable to build RESTful systems, but it's
not designed for RESTful systems. It's designed for traditional web
applications.

Sorry, I don't see the distinction. The Servlet API is designed for handling HTTP requests - what you build on top of that is up to you.

Building web pages, SOAP messages, AJAX or whatever - its all on top of the basic servlet API, not part of it.

Bill

Originally posted by William Brogden:
Sorry, I don't see the distinction. The Servlet API is designed for handling HTTP requests - what you build on top of that is up to you.

I think the point is that there is nothing in the Servlet API itself that will guide you to a more resource-oriented design, avoid overloaded POST operations, creating idempotent operations, etc. A good framework should make the right thing easy to do, while the wrong thing should be harder to do - the Servlet API is too low-level (by itself) to do that for you.