On Nov 18, 2014, at 1:53 PM, Willem Salembier <willem.salembier_at_gmail.com> wrote:
> 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.
>
I ran into this exact problem. +1 for this solution, unless Santiago's mythical hypertext happiness world materializes first ;)
> 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
>>
>>
>
>