Rest – Why use JAX-RS / Jersey

jax-rsjerseyrest

Sorry, this questions sounds silly, but after developing some of my RESTful services using Jersey, I asked myself the question — If REST is just an architecture, and not a protocol like SOAP, why do we need a specification like JAX-RS?

I actually googled for questions like "What is the difference between servlets and RESTful services over HTTP" and to sum up the community answers, I got:

RESTful service development (on Jersey) is an architecture, which inherently uses servlets.
JAX-RS compliant tools like Jersey provide easy marshalling-unmarshalling of XML/JSON data, helping the developers.
REST helps us use GET/POST/PUT/DELETE in a fashion that is far efficient than normal servlets.

According to these answers, I guess if I write a servlet which uses JAXB (for dealing with automatic serialization), and I efficiently use GET/POST/PUT/DELETE in my servlet code, I don't use a tool like Jersey, and hence JAX-RS.

I know I am terribly wrong passing this statement, please correct me.

PS: This doubt actually came in when I had to develop some RESTful services in PHP. After going on through some of the RESTful PHP codes, I realized they are just the same old PHP scripts, with some helper methods for handling XML/JSON.

Best Answer

Why use JAX-RS / Jersey?

Short Answer

Because it makes the development of RESTful services easier.

Long Answer

JAX-RS is a standard that makes it easy to create a RESTful service that can be deployed to any Java application server: GlassFish, WebLogic, WebSphere, JBoss, etc.

JAX-RS is part of Java EE, and when JAX-RS is used with other Java EE technologies it becomes even easier to create your RESTful service:

EJB - A session bean is used as the service implementation and also handles the transaction semantics.
JAX-RS - Used to expose the session bean as a RESTful service
JPA - Used to persist the POJOs to the database. Note how the EntityManager is injected onto the session bean.
JAXB - Used to convert the POJO to/from XML (in GlassFish it can also be used to convert the POJO to/from JSON). JAX-RS by default handles the interaction with the JAXB implementation.

Sample JAX-RS Service

package org.example;

import java.util.List;

import javax.ejb.*;
import javax.persistence.*;
import javax.ws.rs.*;
import javax.ws.rs.core.MediaType;

@Stateless
@LocalBean
@Path("/customers")
public class CustomerService {

    @PersistenceContext(unitName="CustomerService",
                        type=PersistenceContextType.TRANSACTION)
    EntityManager entityManager;

    @POST
    @Consumes(MediaType.APPLICATION_XML)
    public void create(Customer customer) {
        entityManager.persist(customer);
    }

    @GET
    @Produces(MediaType.APPLICATION_XML)
    @Path("{id}")
    public Customer read(@PathParam("id") long id) {
        return entityManager.find(Customer.class, id);
    }

    @PUT
    @Consumes(MediaType.APPLICATION_XML)
    public void update(Customer customer) {
        entityManager.merge(customer);
    }

    @DELETE
    @Path("{id}")
    public void delete(@PathParam("id") long id) {
        Customer customer = read(id);
        if(null != customer) {
            entityManager.remove(customer);
        }
    }

    @GET
    @Produces(MediaType.APPLICATION_XML)
    @Path("findCustomersByCity/{city}")
    public List<Customer> findCustomersByCity(@PathParam("city") String city) {
        Query query = entityManager.createNamedQuery("findCustomersByCity");
        query.setParameter("city", city);
        return query.getResultList();
    }

}

For More Information:

http://blog.bdoughan.com/2010/08/creating-restful-web-service-part-45.html

Related Solutions

Rest – Understanding REST: Verbs, error codes, and authentication

I noticed this question a couple of days late, but I feel that I can add some insight. I hope this can be helpful towards your RESTful venture.

Point 1: Am I understanding it right?

You understood right. That is a correct representation of a RESTful architecture. You may find the following matrix from Wikipedia very helpful in defining your nouns and verbs:

When dealing with a Collection URI like: http://example.com/resources/

GET: List the members of the collection, complete with their member URIs for further navigation. For example, list all the cars for sale.
PUT: Meaning defined as "replace the entire collection with another collection".
POST: Create a new entry in the collection where the ID is assigned automatically by the collection. The ID created is usually included as part of the data returned by this operation.
DELETE: Meaning defined as "delete the entire collection".

When dealing with a Member URI like: http://example.com/resources/7HOU57Y

GET: Retrieve a representation of the addressed member of the collection expressed in an appropriate MIME type.
PUT: Update the addressed member of the collection or create it with the specified ID.
POST: Treats the addressed member as a collection in its own right and creates a new subordinate of it.
DELETE: Delete the addressed member of the collection.

Point 2: I need more verbs

In general, when you think you need more verbs, it may actually mean that your resources need to be re-identified. Remember that in REST you are always acting on a resource, or on a collection of resources. What you choose as the resource is quite important for your API definition.

Activate/Deactivate Login: If you are creating a new session, then you may want to consider "the session" as the resource. To create a new session, use POST to http://example.com/sessions/ with the credentials in the body. To expire it use PUT or a DELETE (maybe depending on whether you intend to keep a session history) to http://example.com/sessions/SESSION_ID.

Change Password: This time the resource is "the user". You would need a PUT to http://example.com/users/USER_ID with the old and new passwords in the body. You are acting on "the user" resource, and a change password is simply an update request. It's quite similar to the UPDATE statement in a relational database.

My instinct would be to do a GET call to a URL like /api/users/1/activate_login

This goes against a very core REST principle: The correct usage of HTTP verbs. Any GET request should never leave any side effect.

For example, a GET request should never create a session on the database, return a cookie with a new Session ID, or leave any residue on the server. The GET verb is like the SELECT statement in a database engine. Remember that the response to any request with the GET verb should be cache-able when requested with the same parameters, just like when you request a static web page.

Point 3: How to return error messages and codes

Consider the 4xx or 5xx HTTP status codes as error categories. You can elaborate the error in the body.

Failed to Connect to Database: / Incorrect Database Login: In general you should use a 500 error for these types of errors. This is a server-side error. The client did nothing wrong. 500 errors are normally considered "retryable". i.e. the client can retry the same exact request, and expect it to succeed once the server's troubles are resolved. Specify the details in the body, so that the client will be able to provide some context to us humans.

The other category of errors would be the 4xx family, which in general indicate that the client did something wrong. In particular, this category of errors normally indicate to the client that there is no need to retry the request as it is, because it will continue to fail permanently. i.e. the client needs to change something before retrying this request. For example, "Resource not found" (HTTP 404) or "Malformed Request" (HTTP 400) errors would fall in this category.

Point 4: How to do authentication

As pointed out in point 1, instead of authenticating a user, you may want to think about creating a session. You will be returned a new "Session ID", along with the appropriate HTTP status code (200: Access Granted or 403: Access Denied).

You will then be asking your RESTful server: "Can you GET me the resource for this Session ID?".

There is no authenticated mode - REST is stateless: You create a session, you ask the server to give you resources using this Session ID as a parameter, and on logout you drop or expire the session.

Java – Input and Output binary streams using JERSEY

I managed to get a ZIP file or a PDF file by extending the StreamingOutput object. Here is some sample code:

@Path("PDF-file.pdf/")
@GET
@Produces({"application/pdf"})
public StreamingOutput getPDF() throws Exception {
    return new StreamingOutput() {
        public void write(OutputStream output) throws IOException, WebApplicationException {
            try {
                PDFGenerator generator = new PDFGenerator(getEntity());
                generator.generatePDF(output);
            } catch (Exception e) {
                throw new WebApplicationException(e);
            }
        }
    };
}

The PDFGenerator class (my own class for creating the PDF) takes the output stream from the write method and writes to that instead of a newly created output stream.

Don't know if it's the best way to do it, but it works.

Best Answer

Related Solutions

Rest – Understanding REST: Verbs, error codes, and authentication

Java – Input and Output binary streams using JERSEY

Related Topic