JAX-RS: Java API for RESTful Web Services is a specification for RESTful Web Services with Java. There is a reference implementation that is included in Java EE but since it
is a specification, other frameworks can be written to implement the spec, and that includes Jersey, Resteasy, and others. Jersey is the implementation of JAX-RS.
The JAX-RS API uses annotations to simplify the development of RESTful services. Annotations, along with the classes and interfaces provided by JAX-RS API, allow you to expose simple POJOs as web resources. Because of its heavy reliance on annotations, JAX-RS requires Java 5 and above.
As with any other Java web application, you bundle JAX-RS applications as a WAR file and deploy them on a container that supports Servlets. You use the Servlets provided by the container to route the requests to the appropriate web resource. A goal of JAX-RS is to enable the portability to deploy web resources across different types of web containers.
Sun offers a reference implementation for JAX-RS code-named Jersey. Jersey uses a HTTP web server called Grizzly, and the Servlet Grizzly Servlet (com.sun.jersey.spi.container.servlet.ServletContainer) handles the requests to Grizzly. You can develop production-quality JAX-RS applications today using Jersey, which implements all the APIs and provides all the necessary annotations for creating RESTful web services in Java quickly and easily. Beyond the set of annotations and features defined by JAX-RS.
Developing RESTful Web Services Using JAX-RS
The classes and interfaces you use for creating RESTful web services with JAX-RS are available in the following packages:
HTTP Status Codes
HTTP response codes standardize a way of informing the client about the result of its request. The header() function prints the HTTP headers and ensures that they are
formatted appropriately. Headers should be the first thing on the response, so you shouldn't output anything else before you are done with the headers. Sometimes, your
HTTP server may be configured to add other headers, in addition to those you specify in your code.
Headers contain all sort of meta information; for example, the text encoding used in the message body or the MIME type of the body's content. In this case, we are explicitly specifying the HTTP response codes. HTTP response codes standardize a way of informing the client about the result of its request. Keep in mind that the meaning of a HTTP response code is not extremely precise; this is a consequence of HTTP itself being rather generic. You should attempt to use the response code which most closely matches the situation at hand. That being said, do not worry too much if you cannot find an exact fit. In general status code are grouped into a few different categories:
- 1xx is all about information
These are not used a lot.
- 2xx is all about success
Whatever the client tried to do was successful up to the point that the response was send. Keep in mind that a status like 202 Accepted doesn't say anything about the actual result, it only indicates that a request was accepted and is being processed asynchronously.
- 3xx is all about redirection
These are all about sending the calling application somewhere else for the actual resource. The best known of these are the 303 See Other and the 301 Moved Permanently which are used a lot on the web to redirect a browser to another URL.
- 4xx is all about client errors
With these status codes we indicate that the client has done something invalid and needs to fix the request before resending it.
- 5xx is all about service errors
With these status codes we indicate that something went wrong in the service. For example a database connection failed. Typically a client application can retry the request. The server can even specify when the client is allowed to retry the command using a Retry-After HTTP header.
Here are few status codes, which are often used:
This response code indicates that the request was successful.
This indicates the request was successful and a resource was created. It is used to confirm success of a PUT or POST request.
300 Multiple Choice
The requested resource corresponds to any one of a set of representations, each with its own specific location, and agent- driven negotiation information is being provided so that the user (or user agent) can select a preferred representation and redirect its request to that location.
301 Moved Permanently
The requested resource has been assigned a new permanent URI and any future references to this resource SHOULD use one of the returned URIs. Clients with link editing capabilities ought to automatically re-link references to the Request-URI to one or more of the new references returned by the server, where possible. This response is cacheable unless indicated otherwise.
400 Bad Request
The request was malformed. This happens especially with POST and PUT requests, when the data does not pass validation, or is in the wrong format.
404 Not Found
This response indicates that the required resource could not be found. This is generally returned to all requests which point to a URL with no corresponding resource.
This error indicates that you need to perform authentication before accessing the resource.
405 Method Not Allowed
The HTTP method used is not supported for this resource.
This indicates a conflict. For instance, you are using a PUT request to create the same resource twice.
500 Internal Server Error
When all else fails; generally, a 500 response is used when processing fails due to unanticipated circumstances on the server side, which causes the server to error out.
It's important to remember that HTTP was conceived to communicate between systems, which share nothing but an understanding of the protocol. In general, the less assumptions beyond HTTP you make, the better: this allows the widest range of programs and devices to access your API.