Should a REST API implemented with jax-rs return an interface or an implementation

Question

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.

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”.