I think that I know the answer, but I would like to be sure.

When jax-rs is used to implement a REST API, a @GET method should return an interface, implementation or an abstract implementation ?

If it returns an interface, sometimes it won't be obvious to know what it is really returning: for example, the json serialization of one instance of this interface can be completely different from the json serialization of another instance. In the same time, we won't know how to deserialize the json on the client side.

If it returns an implementation, it won't be easy to substitute this implementation class with something else. There could be use cases where we won't to be able to offer a customisable API to system integrators.

I do not want to open a debate: I want to know what is usually done in real use cases.

  • It should return data, not an implementation. Why would it be different just because you are using jax-rs?
    – Rob
    Commented May 3, 2017 at 13:46
  • if you ask a website for /header.gif are you expecting header.gif or whatever the server decides to send?
    – Richard
    Commented May 5, 2017 at 23:31
  • @Rob - The question is about jax-rs because this is what is used to implement the API. I know that the API returns data, but I want to know how to define it in Java. It is important, for example, because tools like jax-rs-to-raml are able to generate a raml file starting from the jax-rs definition. If I use an interface, the tool will not be able to know what class I am returning. If I return an implementation, I am stuck with that class that is bad.
    – Ward Clark
    Commented May 7, 2017 at 18:57
  • 1
    Unless you are implementing a framework (which usually works with abstractions) just return concrete classes. As developer I would not feel confident with a REST API that implements ambiguity on its interface. As client of the API i don't care about your levels of abstraction. I want concrete and unambiguous resources. Anyways you are just going to return DTOs. I don't see why a DTO needs inheritance.
    – Laiv
    Commented Jun 4, 2017 at 17:29

1 Answer 1


As you probably assume already, the answer is it depends. It depends on what you want to do.

Your clients don’t care what your REST API implementation is, if it’s JAX-RS, plain servlets, or whatever. They care about the resources your service exposes and how to interact with their representations (which are mostly done with JSON or XML).

Let’s pick on JSON which is what you are most likely using since most JAX-RS tutorials out there use Jackson for serialization. A library like Jackson - by default - looks at the actual object when it does the serialization, its public getters and setters, and not at the interface(s) of the object. So, it does not matter if your @GET annotated method returns an interface or a method. This only matters for how you are implementing the service. Not for your clients. For you!

Using an interface instead of an implementation gives you some advantages. Read here for example: https://stackoverflow.com/questions/383947/what-does-it-mean-to-program-to-an-interface

But again, these are advantages for you as a developer of the service, your client isn’t aware of the implementation of the service, only on the data it exchanges with it.

There are also disadvantages. If your controllers return all interfaces how do you know which ones return, say, a Customer and which ones return an Invoice. You don’t, because you decided that all return an Entity (or whatever is the common interface), and now you need to look in the code to see what each method is returning. Also, some developer working with you on the service might decide that at some point the same method can return both a Customer and an Invoice just because the return type allows it to be any Entity. And now you have a weird behaving REST API.

Like I said, it depends on what you want to do. There is not only one thing “usually done in real use cases”.

  • I am sorry but your answer does not really help. What is the usual practice when implementing an API using jax-rs? Returning an interface or an implementation?
    – Ward Clark
    Commented May 7, 2017 at 19:09
  • "Usual practice" for whom? All depends on your particular context. That's what my answer is saying. I'm sorry it wasn't what you were looking for.
    – Bogdan
    Commented May 14, 2017 at 9:15

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.