Dear Peter,
thank you a much for the first draft. Forwarding to the users
list so that we can get some feedback from others as well.
My comments will follow in another message.
~Jakub
----- Forwarded message from Peter Schonhofen <schonhofen_at_gmail.com> -----
Date: Sun, 20 Apr 2008 23:28:39 +0200
From: Peter Schonhofen <schonhofen_at_gmail.com>
Subject: Jersey overview
To: Jakub Podlesak <Jakub.Podlesak_at_Sun.COM>
Dear Jakub,
Here is a first attempt for an overview page. Feel free to modify, extend,
correct it,
as my English language skills and knowledge about Jersey are far from
optimal :-)
Peter
What is Jersey?
Jersey is an implementation of JSR-311, an upcoming standard for RESTful web
services for Java. Since JSR-311 is not finalized yet, Jersey always tries to
comply with the last published draft version, and it is therefore subject to
change. However, it enables you to experiment with this new technology and
write prototype code to see how can it be leveraged in your future projects.
What is a RESTful web service?
As opposed to "regular" web services with which you communicate through SOAP
messages, RESTful web services can be accessed via the much simpler and more
well-known HTTP GET, POST, PUT, DELETE methods, making it easier for non-Java
clients (e. g. Javascript or Perl) and for developers not familiar with web
services to invoke its operations. Of course, however, you have to pay a price
for it. First, you lose -- or at least have to implement yourself -- many
sophisticated features like security, reliable transport, optimized message
transfer, registries etc., available in "regular" web services. Second, you
have to adapt your public API to the Internet principles: URLs should strictly
refer to entities or resources which have to be manipulated and should not
contain neither the operation code nor any data; instead, you should map your
operations only to queries (GET), modifications or creations (POST, PUT), and
removals (DELETE).
What can you do with Jersey (and JSR-311)?
Fortunately, Jersey can be leveraged mainly through annotations, so you do not
need to write any XML configurations files. You can attach Java methods to
combinations of particular URL patterns and HTTP methods; you can designate
the resource or entity IDs inside the URL pattern, which then get passed to
the Java method as traditional parameters. In POST-type invokations you can
receive the data in several formats, such as plain text, JSON, XML, HTML form
parameters, Atom RSS and so on. You can control the format of JSON output to
some degree, e. g. removing the root element or forcing certain elements to
be represented as arrays regardless of whether they contain only one or many
values. You can receive auxiliary parameters encoded in the URL, for example
the number of entities to show when querying the list of available entities,
through method parameters, and specifying default values for them. And of
course you get a nice HTML interface through which you can test your RESTful
web services and inspect the raw output.
Where can I find more information?
...
Where can I find examples?
...
What are the other possibilities to implement RESTful web services?
Restlets (
http://www.restlet.org)
Apache Axis
...
----- End forwarded message -----