REST is the underlying architectural principle of the web. The amazing thing about the web is the fact that clients (browsers) and servers can interact in complex ways without the client knowing anything beforehand about the server and the resources it hosts. The key constraint is that the server and client must both agree on the media used, which in the case of the web is HTML.
An API that adheres to the principles of REST does not require the client to know anything about the structure of the API. Rather, the server needs to provide whatever information the client needs to interact with the service. An HTML form is an example of this: The server specifies the location of the resource and the required fields. The browser doesn't know in advance where to submit the information, and it doesn't know in advance what information to submit. Both forms of information are entirely supplied by the server. (This principle is called HATEOAS: Hypermedia As The Engine Of Application State.)
So, how does this apply to HTTP, and how can it be implemented in practice? HTTP is oriented around verbs and resources. The two verbs in mainstream usage are GET and POST, which I think everyone will recognize. However, the HTTP standard defines several others such as PUT and DELETE. These verbs are then applied to resources, according to the instructions provided by the server.
For example, Let's imagine that we have a user database that is managed by a web service. Our service uses a custom hypermedia based on JSON, for which we assign the mimetype application/json+userdb (There might also be an application/xml+userdb and application/whatever+userdb - many media types may be supported). The client and the server have both been programmed to understand this format, but they don't know anything about each other. As Roy Fielding points out:
A REST API should spend almost all of its descriptive effort in
defining the media type(s) used for representing resources and driving
application state, or in defining extended relation names and/or
hypertext-enabled mark-up for existing standard media types.
A request for the base resource / might return something like this:
Request
GET /
Accept: application/json+userdb
Response
200 OK
Content-Type: application/json+userdb
{
"version": "1.0",
"links": [
{
"href": "/user",
"rel": "list",
"method": "GET"
},
{
"href": "/user",
"rel": "create",
"method": "POST"
}
]
}
We know from the description of our media that we can find information about related resources from sections called "links". This is called Hypermedia controls. In this case, we can tell from such a section that we can find a user list by making another request for /user:
Request
GET /user
Accept: application/json+userdb
Response
200 OK
Content-Type: application/json+userdb
{
"users": [
{
"id": 1,
"name": "Emil",
"country: "Sweden",
"links": [
{
"href": "/user/1",
"rel": "self",
"method": "GET"
},
{
"href": "/user/1",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/1",
"rel": "delete",
"method": "DELETE"
}
]
},
{
"id": 2,
"name": "Adam",
"country: "Scotland",
"links": [
{
"href": "/user/2",
"rel": "self",
"method": "GET"
},
{
"href": "/user/2",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/2",
"rel": "delete",
"method": "DELETE"
}
]
}
],
"links": [
{
"href": "/user",
"rel": "create",
"method": "POST"
}
]
}
We can tell a lot from this response. For instance, we now know we can create a new user by POSTing to /user:
Request
POST /user
Accept: application/json+userdb
Content-Type: application/json+userdb
{
"name": "Karl",
"country": "Austria"
}
Response
201 Created
Content-Type: application/json+userdb
{
"user": {
"id": 3,
"name": "Karl",
"country": "Austria",
"links": [
{
"href": "/user/3",
"rel": "self",
"method": "GET"
},
{
"href": "/user/3",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/3",
"rel": "delete",
"method": "DELETE"
}
]
},
"links": {
"href": "/user",
"rel": "list",
"method": "GET"
}
}
We also know that we can change existing data:
Request
PUT /user/1
Accept: application/json+userdb
Content-Type: application/json+userdb
{
"name": "Emil",
"country": "Bhutan"
}
Response
200 OK
Content-Type: application/json+userdb
{
"user": {
"id": 1,
"name": "Emil",
"country": "Bhutan",
"links": [
{
"href": "/user/1",
"rel": "self",
"method": "GET"
},
{
"href": "/user/1",
"rel": "edit",
"method": "PUT"
},
{
"href": "/user/1",
"rel": "delete",
"method": "DELETE"
}
]
},
"links": {
"href": "/user",
"rel": "list",
"method": "GET"
}
}
Notice that we are using different HTTP verbs (GET, PUT, POST, DELETE etc.) to manipulate these resources, and that the only knowledge we presume on the client's part is our media definition.
Further reading:
(This answer has been the subject of a fair amount of criticism for missing the point. For the most part, that has been a fair critique. What I originally described was more in line with how REST was usually implemented a few years ago when I first wrote this, rather than its true meaning. I've revised the answer to better represent the real meaning.)
Best Answer
TL;DR
JAX-WS is meant for XML based web services such as SOAP. JAX-RS does not have the same restriction.
JAX-WS is generally geared towards server to server interactions with well defined contracts (WSDLs) and usually when the service and client side are from separate groups. It is very resource intensive so it isn't feasible for client-to-server interactions where the network or client device capability is less than optimal.
JAX-RS is geared towards client to server interactions, although server-to-server is okay. As it has little service obligations, it can be tuned to whatever the client needs are.
More info
The JAX-RS API only provides code-first approaches, whereas JAX-WS allows for both code-first (generally not recommended) and contract-first using WSDL files (more commonly recommended).
JAX-RS 2.0 introduces the client API which is a smart wrapper for HttpUrlConnection that has a lot more mapping capability, JAX-WS is also a wrapper, but the data it deals with in the reference implementations is just XML.
JAX-RS has the advantage of creating APIs that are simpler to create and digest messages for in different browsers and mobile devices, namely JSON structure. It does not introduce the notion of an envelope and uses HTTP for it. It does not introduce cryptography or security, it uses HTTPS for it.
JAX-WS though it runs on HTTPS for cryptography provides additions for security using WS-SecurityPolicy etc. In addition, contracts are firmly established using WSDL and can be verified outside the application using ESBs such as DataPower.
So what to choose
JAX-WS is generally geared towards server to server interactions with well defined contracts (WSDLs) and usually when the service and client side are from separate groups. It is very resource intensive so it isn't feasible for client-to-server interactions where the network or client device capability is less than optimal.
JAX-RS is geared towards client to server interactions, although server-to-server is okay. The only contractual obligation between a client and server is the message and the request headers. As it has little service obligations, it can be tuned to whatever the client needs are.
However, using RESTful service APIs is akin to doing meta-programming like Ruby and Python which delays problems to run-time as there is no defined schema agreed and technically enforced upon by the two sides. As such I don't recommend RESTful services everywhere, but I would recommend it if I had control of the two sides which normally happens when you do build a web application that uses static HTML/CSS/JS and talks with a RESTful server for the data.