I am working on building a REST api. My question is, when using Jersey, what are the differences between my services building and returning a Response object or returning the the bean or collection. I am only concerned with successful calls, I am throwing appropriate exceptions for errors and exceptional situations.
Here is a example:
@Produces(MediaType.APPLICATION_JSON)
public Response search(FooBean foo){
List<FooBean> results = bar.search(foo);
return Response.ok(results).build();
}
vs.
@Produces(MediaType.APPLICATION_JSON)
public List<FooBean> search(FooBean foo){
List<FooBean> results = bar.search(foo);
return results;
}
I've seen both examples used, and I'd prefer the second scenario, just to make it easier to recognize the service method. I've examined the responses to both of these methods and they appear to be identical.
Thoughts?
The differences are explained in the JAX-RS specification:
'Regular' beans are mapped over in pretty much the same way as
Response
is, with the exception that aResponse
allows you to set additional metadata (response headers, specialized status, specialized content type, etc). As far as which one to use, thats entirely up to you too decide -Response
gives you more flexibility, but regular beans are more 'self-documenting'.There is no diference if you want to return always the response
200 - OK
, catching and manipulate all the exceptions that may occur before of after your method return the result, with interceptions orWebApplicationException
. So, both of these methods will result the same responses.The only diference is at specific scenarios, like returning null objects, or creating object, like this example:
In this case the return will be
201 - CREATED
(With the URI to access the created object)So, the following method:
... will return a response
200 - OK
If you don't care about which response status your client will receive, you can use any of declarations without problem.
Source: Jersey.
My personal of view, if response contains DTO (Bean/Collection of beans), then rest service always must return DTO, but not Response object.
The motivation: early or late, you will be asked to make a usage of rest service easier for clients, by providing rest client api. Usually, you have to extract rest interfaces for it, and implement them with your rest services. These rest interfaces are used by clients of your rest client.
And from a client point of view there is a huge difference between processing DTO and plain Response. In case Response is used, your client is forced:
Which means handling Response is very similar to returning error codes in methods, which is considered as a very bad practice. In order to handle errors in one place, exceptions are used (I'm not talking about FP ways of handle errors, which is the best).
So what may you do:
So if to think in advance, you should return DTO.
One use-case, when plain Response should be returned - when you export file, for instance. It seems JAX RS does not allow to return InputStream object. Not sure, it has to be checked.
The other use case, was pointed by @Perception, but it is more an exception, than a rule:
Note: it is a general question for JAX RS, does not depend on exact implementation, like Resteasy or Jersey