Best practices for method types in JAX-RS

Question

What are the best practices regarding the method types in JAX-RS ?

I am interested in the following methods: GET, POST, PUT and DELETE.

My possible approaches:

GET - always return a response.

@GET
@Path("/path/{something}")
public T getT() {
    ...
    return t;          // t - instance of T
}

POST

@POST
@Path("/path")
public T/void createOrUpdate() {
    ...
    return t;          // t - instance of T
}

Q: Is it better to return the entire created resource or just an "ACK response" or to have a void method? What about a POST that is used as GET (when we want to avoid the URL length limitation)?

PUT

@PUT
@Path("/path")
public T/void createOrUpdate() {
    ...
    return t;          // t - instance of T
}

Q: Is it better to have a void method or a response for the created/updated resource or different responses for creation / update or just an ACK response ?

DELETE

@DELETE
@Path("/path/{something}")
public T/void deleteT() {
    ...
    return t;          // t - instance of T
}

Q: Is is better to have a void method or to return the deleted resource or to return an ACK response ?

Is it ok to always have T = javax.ws.rs.core.Response (when T is used)?

I saw that:

• Lars Vogel uses GET - T, POST - void, PUT - T, DELETE - void
• Oracle uses GET - T, POST - T/void, DELETE - void

Answer 1

JAX-RS is a specification for developing 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.

JAX-RS as such does not lay down any guidelines on the return types and response codes for the REST API's. However, there are a few guidelines (these are not hard and fast rules) in the REST standard which you might want to follow:

Method                  GET     
Successful Response     RETURN the resource with 200 OK  
Failure Response        RETURN appropriate response code

Method                  POST  
Successful Response     RETURN the link to the newly created resource in Location response  header with 201 status code  
Failure Response        RETURN appropriate response code

Method                  PUT  
Successful Response     RETURN the updated resource representation with 200 OK or return nothing with 204 status code   
Failure Response        RETURN appropriate response code

Method                  DELETE  
Successful Response     RETURN nothing with 200 or 204 status code  
Failure Response        RETURN appropriate response code

In practice, POST works well for creating resources. The URL of the newly created resource should be returned in the Location response header. PUT should be used for updating a resource completely. Please understand that these are the best practices when designing a RESTful API. HTTP specification as such does not restrict using PUT/POST with a few restrictions for creating/updating resources. Take a look at Twitter REST API best practices that summarizes the best practices for RESTful API's.