users@jax-rs-spec.java.net

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

From: Santiago Pericas-Geertsen <Santiago.PericasGeertsen_at_oracle.com>
Date: Tue, 18 Nov 2014 16:08:25 -0500

Willem,

 API are just tools, it ultimately depends on how they are used. The point is that proxy-based APIs seems to "encourage" the wrong design decisions by trying to mimic the server-side resource structure. The moment you bring hypermedia into the equation, they become a lot less attractive.

 Yes, some implementations support proxy-based APIs, but that doesn't mean it's the most popular choice (in fact in our case, it is not). At the moment, it is not on the agenda for JAX-RS 2.1 to support such an API. You can always create a JIRA and try to gather supporters for it ;)

 Thanks.

-- Santiago

On Nov 18, 2014, at 3:44 PM, Willem Salembier <willem.salembier_at_gmail.com> wrote:

> 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 website.
>
> Client client = ClientBuilder.newClient();
> WebTarget target = client.target("https://graph.facebook.com/");
> target = target.path("{id}").resolveTemplate("id", id);
>
> Response response = target.request().get();
> FBUser user = builder.get(FBUser.class);
>
> vs
>
> @Path("/")
> public interface FacebookAPI {
> @GET
> @Path("{id}")
> 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?
>
> Willem
>
>
> On Tue, Nov 18, 2014 at 8:39 PM, Santiago Pericas-Geertsen <Santiago.PericasGeertsen_at_oracle.com> 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] http://www.hydra-cg.com/
>
>
> On Nov 16, 2014, at 3:53 AM, willem.salembier_at_gmail.com 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:
>> http://docs.jboss.org/resteasy/docs/1.0.1.GA/userguide/html/RESTEasy_Cl
>> ient_Framework.html
>>
>> http://cxf.apache.org/docs/jax-rs-client-api.html#JAX-RSClientAPI-Proxy
>> -basedAPI
>>
>>
>> https://jersey.java.net/apidocs/2.9/jersey/org/glassfish/jersey/client/
>> proxy/package-summary.html
>>
>> http://square.github.io/retrofit/
>>
>> https://github.com/Netflix/feign
>>
>> Best regards,
>> Willem Salembier
>
>