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.

Answer 2

This answer is not correct/up to date. Please check @ROMANIA_engineer answer instead.

You should never return void. The best practice is to always return a javax.ws.rs.core.Response . But note that even if you define the webresource with void , your server will return a HTTP response.

On POST and PUT , it may be better to return the modified resource, including its id. Some front-end framework and/or middleware will use it to synchronise the resource with your server (as instance, see Backbone Model ).

On DELETE , it depends of the action you try to achieve.. But usually an ACK is enough.

NB : Anyway, whatever you return, don't forget to respect your security policies !

---

Response @Atul : When you send HTTP Request from client or HTTP Response from your server, some data may be protected. As instances :

• On user update (username, password, or anything else) do not return the user password in the HTTP Response.
• When user log in, you better use a HTTPS protocol and never send the password in plaintext
• .. etc

Answer 3

I give it a shot and state a "no there is no best practice". This because the underlying protocol (HTTP) actually has return values (such as 200-OK, 500-Internal Error...) in any case unless a broken connection which should be followed by your service as well.

Since you are not implementing the HTTP-Protocol but a own-designed service following its own rules, no there is no best practice, you will have to define "your protocol" in a way it matches your day to day business the best.

For example when it comes to your delete operation a caller could either not be interested in a response at all or as well expect you to work like a stack and return him the "deleted/removed" element on call. It is up to you to know what fits your needs best.