5

In some books, the rest APIs generally return a Response object which wraps some other objects representing payload, status, etc.

On the other hand many of the APIs that I have seen and written return a POJO (or call it a DTO) as JSON which is the consumed by the client.

This may be opinion based, but I would like to know which is better of the two to use on high scalability environment where some request result in success and others in failure/data not returned.

I would like to know if there is an accepted better practice. This will help me designing some APIs and put things in perspective before my team. But I am ok with this question being closed if 'better of the two' is too much opinion based.

Thanks.

Update: The two rest APIs would look like this. Avoiding code like @Path, @Get, @PathParam, @Produces etc

public Response myCustomerObject(int id){...}

This returns a Customer object wrapped inside the Response object. Response could be error as well.

And the approach below will return the Customer entity directly:

public Customer myCustomerObject(int id){...}
Atul
  • 2,673
  • 2
  • 28
  • 34
  • 1
    Could you please come up with two examples? That way it should be easier to understand. – Alberto Zaccagni Jul 08 '15 at 13:25
  • 2
    REST-APIs have nothing to do with the concrete implementation of some framework you use - especially if you use a Response object vs. POJO. A POJO will be marshalled to the desired output format understood by the client (Accept header) by the underlying framework and return a default response code (if not specified through annotations or exception (handlers) otherwise). A Response object will specify the return code and the entity returned explicitely - though the marshalling may be done automatically as well. – Roman Vottner Jul 08 '15 at 13:29
  • @AlbertoZaccagni will add an example. – Atul Jul 08 '15 at 13:32
  • @RomanVottner So, the pros-cons are basically about explicit handling of response codes etc. I am curious about what are industry followed practices in general. Anyway, this was a nice answer. Could you post it as one instead of comment so that I could accept if there is no better answer in a day or so? Thanks. – Atul Jul 08 '15 at 15:01
  • 1
    http://stackoverflow.com/questions/16303544/in-jersey-differences-between-returning-response-and-bean-or-collection-of-bean – Herupkhart Oct 11 '16 at 03:27
  • @GeorgeLaed Thanks. – Atul Oct 12 '16 at 08:19

3 Answers3

6

I would vote for an API which gives you a Response object. This allows you to control the response completely within your code and it is clear what is going into response. And in cases where you want to write a Response which cannot easily be represented by a POJO you are not forced to use unintuitive workarounds.

Returning a Object from a rest handler method which is then transformed into a response is too much framework magic for my taste.

Worst - imho - is the practice to return a String from the rest handler method which is then interpreted as a template reference (e.g. the path to a JSP resource) which is then written to the response. Again way too much magic.

wero
  • 32,544
  • 3
  • 59
  • 84
5

I prefer returning custom data objects instead if response objects. The whole point of the annotation based frameworks is to abstract away the http aspects from the application logic. Instead of managing response codes and entities, application developers return model objects and throw custom exceptions that can be mapped to http codes in a mapper. It's less control but IMHO it's way easier to rapidly develop an api.

toadzky
  • 3,806
  • 1
  • 15
  • 26
1

The one returning response object contains your data is getting legacy of request/response services like SOAP and HTTP, but REST services build on concept of resources not request/response so I prefer to use objects represents your actual resources without wrapper, how could rest service represents your resources direct on response object for ex. if you are calling resource like car:

http://localhost/car GET for list of cars

http://localhost/car/1 GET for getting car with id 1

how to represent this in response object ?

Bassem Reda Zohdy
  • 12,662
  • 3
  • 33
  • 39
  • 1
    In JAX-RS you annotated methods with f.e. `@Path("/car")` or `@Path("/car/{id}") which will therefore invoke the corresponding method which may return a `Response.status(Response.Status.OK).entity(...).build()` instance, where the concrete entity is either marshalled by you or marshalled by the framework on passing the POJO as entity. – Roman Vottner Jul 08 '15 at 13:52
  • what I mean is that if you are returning response object to contains you response data will not be sync with concept of rest service which is expect list of cars in case if "/car" and one car in case of "/car/{id}", but if you are use request/response will get response wrapper in 2 cases – Bassem Reda Zohdy Jul 08 '15 at 15:32