[jax-rs-spec users] Re: Proxy-based client API

From: Willem Salembier <>
Date: Tue, 18 Nov 2014 21:44:06 +0100

Hello Santiago,

Thanks for your feedback. I recognize that in the future there is an
opportunity for strong hypermedia-driven API's that use JSON-LD
extensively. But I think it's premature to state all API's will evolve in
this way. I also think the Hydra approach is not generalizable to all use
cases. Eg a backend system that invokes one specific API-call to retrieve
some data from a Restful service.

Look at the Facebook Graph API. Its documentation is limited to a html

Client client = ClientBuilder.newClient();
WebTarget target ="");
target = target.path("{id}").resolveTemplate("id", id);

Response response = target.request().get();
FBUser user = builder.get(FBUser.class);


@Path("/") public interface FacebookAPI {
FBUser getUserInfo(@PathParam("id") String id);

FacebookAPI endpoint = /* initialize client */;
FBUser user = endpoint.getUserInfo(id);

Both implementations have the same degree of coupling, because the API is
hardcoded in both cases. I do think the second implementation is nicer.
Additionally, any developer writing this code, will benefit from knowing
the concepts used at server-side.

A small comparisong to the JAX-WS specification. It provides a low-level
API through the *javax.xml.soap* packages, but also high-level annotation
driven API using *javax.jws*. At this moment, the JAX-RS API seems
unbalanced providing an entirely different API on clientside.

The fact that all major JAX-RS implementations provide some kind of
proxy-based extension, merits that we reopen the discussion and re-evalute
its strong and weak points. Will the JAX-RS experts consider this?


On Tue, Nov 18, 2014 at 8:39 PM, Santiago Pericas-Geertsen <> wrote:

> Willem,
> The topic of a proxy-based client API or higher-level API was discussed
> during JSR 339 (JAX-RS 2.0). Although it does simplify development for some
> clients, a lot of experts believe this is not right model to access RESTful
> services due to the additional coupling (apparent or real) introduced
> between clients and servers.
> The "next generation" of RESTful services is likely going to be much more
> hypermedia driven, for which proxy-based APIs aren't a great fit. I
> encourage you to look at the work done in Hydra [1] --there's already a W3C
> recommendation under way.
> -- Santiago
> [1]
> On Nov 16, 2014, at 3:53 AM, wrote:
> What is the status of standardizing a proxy-based client API in JAX-RS?
> The current client API is rather low-level.
> The main goal is to reuse the same JAX-RS annotations on an interface
> client-side. The implementation creates a stub which a client can use
> to call a restful resource. This model brings the same simplicity we
> have on the serverside to the client.
> All JAX-RS implementations have some kind of proxy-based extension
> nowadays and it is also the core idea of frameworks like Square's
> Retrofit and Netflix Feign.
> Some references:
> ient_Framework.html
> -basedAPI
> proxy/package-summary.html
> Best regards,
> Willem Salembier