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