users@jax-rs-spec.java.net

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

From: Willem Salembier <willem.salembier_at_gmail.com>
Date: Tue, 18 Nov 2014 22:53:45 +0100

I created a JIRA https://java.net/jira/browse/JAX_RS_SPEC-496

When I look at all the client examples in JSR 339, they always mimic
server-side resources in a hardcoded way. So I don't think the proposed
usage is that wrong. Just my 2 cents.

Thanks for your feedback.

Best regards,
Willem

On Tue, Nov 18, 2014 at 10:08 PM, Santiago Pericas-Geertsen <
Santiago.PericasGeertsen_at_oracle.com> wrote:

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