JAX-RS Compatibility

[nobeh]

I understand that one focus of this nice library is aimed at Android.

I am interested to know what where the design decisions/concerns to have

@GET("/api/users/{id}"
public User getUser(@Path("id") String id);

rather than having JAX-RS spec API and then:

@GET
@Path("/api/users/{id}")
public User getUser(@PathParam("id") String id);

Thanks. And, any plans to support the spec?

[JakeWharton]

Retrofit is focused solely on the client-side and the annotations are customized for such. See #573 for more.

And, any plans to support the spec?

Unless a very, very compelling argument can be made (and I haven't seen one yet), no.

[JakeWharton]

Retrofit is also 4+ years old so it pre-dates JAX-RS 2 (which has better annotations than JAX-RS 1 for clients) by some time.

[nobeh]

Thanks for the explanations. I do not intend to make an argument here but I have to say, in my opinion, what distinguishes Retrofit from others is that it allows to share/reuse unified interface signatures across different layers; i.e. define an interface in a one place, use it in a "backend" layer (of course with a different supporting library) and again use it again in a "presentation" layer.

[JakeWharton]

With 2.0 we're going to move even farther away from the ability to share making this impossible. I admire your desire to do this. I spent a good two days evaluating compatibility back in 2012 but deemed it impossible then and as we are focusing even more on client-specific behavior with 2.0 I simply don't think we can ever really do this.

What I would recommend doing is using an alternative format for representing your API endpoints and generating both the Retrofit service interface and the JAX-RS one for server side.

For example, we use protocol buffers:

service FooService {
  // @url /bar
  // @method POST
  rpc BarResponse bar(BarRequest);
  // @url /baz
  // @method POST
  rpc BazResponse baz(BazRequest);

which generate types and becomes:

interface FooService {
  @POST("/bar")
  BarResponse bar(BarRequest body);

  @POST("/baz")
  BazResponse baz(BazRequest body);
}