JAX-RS annotations: Better to put on Interfaces or Classes?

Question

I am early on in a REST implementation and have recently learned that we could be putting our JAX-RS annotations on our Java service interfaces rather than the class implementations.

To me it seems like this could result in a clean class file, but might also result in developers have to constantly muddle between files.

What are the pros and cons of each approach?

Answer 1

You should put it in an interface. Rather, my practice requires me to put it into an interface, because my client and server sides are sharing the same jax-rs definition.

I am inclined to use jax-rs for REST-RPC.

The reason for REST is to allow an web service URL API to be serviceable and "clientable" by any programming framework.

The use of jax-rs restricts us to using java on the server side.

The use of jax-rs for REST-RPC restricts us to using java on both server and client sides.

What is REST-RPC?

In a not too convoluted attitude of explanation, RPC is a way of calling a function/method on the client, which when sent over the wire is serviced by the server such that the same function/method exists on the server side.

RestEasy allows you to use the jax-rs definition on the client-side to call the same function serviced on the server side.

RestyGWT, too, with some modification to the interface to specify a callback method would allow you to (somewhat) use the jax-rs definition on both client and server side. You simply have to write a script to move the return type to the type argument of the callback method.

You might question why restrict ourselves to performing java on both sides? Would that not defeat one of the purposes in life of REST? I think jax-rs REST-RPC is a convenient route to implementing and testing a jax-rs service. If you wanted to implement a jax-rs service, you probably would do it initially in Java on both sides anyway. And then when your service gets off the ground, you could start writing PHP or python clients.

Writing your jax-rs in interface files would allow you to publish your interface for client side operations. This is especially true for REST-RPC. However, you could run enunciate over your jax-rs definition to publish your web service API to non-java programmers.

I have some ongoing rambling on this subject... http://h2g2java.blessedgeek.com/2011/11/gwt-with-jax-rs-aka-rpcrest-part-0.html.