Clarify what an interface looks like

[johnament]

The base of the spec should include rough details about what a rest client looks like.

[derekm]

I'm using Jersey's WebResourceFactory with this patch: https://github.com/jersey/jersey/pull/235

I've achieved very successful results with this setup. The REST client I've built out with it exactly models the URL structures of the services I'm hitting (not a requirement of the setup I'm using, just a technique I'm using in organizing the resource interfaces).

I think it would be smart for MicroProfile REST Client leads to analyze this approach.

[johnament]

@derekm that's useful to know. I was under the impression that the jersey framework didn't support proxying. This is the approach we are considering.

[johnament]

I'm adding the help wanted label to this. I would like to see more people include sample interfaces of what they expect should be supported. Note that each example should include a TCK test.

Might be good for early on contributors like @andymc12 and @derekm if interested :-)

[johnament]

Based on some input, I think we should include some of the following:

• With and without @Path at the interface level
• Subresources
• BeanParams

[johnament]

For the first bullet point, here's an example of the interface:

public interface MyClient {
    @GET
    Response get();
}

MyClient client = RestCientBuilder.newBuilder().baseUrl("https://www.google.com").build(MyClient.class);

[johnament]

For bullet point two:

public interface MyClient {
   @Path("/")
   Google google();
}

public interface Google {
   @GET
   Response get();
}

[johnament]

bullet 3:

public class MyBean {
   @QueryParam(name="query")
   private String language;
   @CookieParam(name="cookie")
   private String myCookie;
   @HeaderParam(name="Accepts")
   private String acceptsHeader;
// getters setters constructors
}

public interface MyClient{
    @GET
    Response get(@BeanParam MyBean myBean);
}

[johnament]

For the @Path case, we should clarify in the spec that the use at the interface level is optional. If we want to append to the base URL, we can add @Path. In addition, if the individual API methods have additional URI elements those can be appended at the method level.

The rest client supports all of the @*Param types as defined by JAX-RS as method arguments.

To define a method that returns a sub-resource interface, it should be annotated with any verb. It may be annotated with any @Path annotation to append to the URI. The return type must be an interface and is expected to be proxied the way other API calls are proxied in the parent resource.

[derekm]

Another feature the Jersey community is asking for is parameter converters, as seen in this PR to the Jersey codebase: https://github.com/jersey/jersey/pull/269

In Jersey-land, the BeanParam Support & Parameter Converters Support PRs are in conflict. If MP Rest Client could get ahead of these concerns & support both in one go, that would be huge for pushing the Java development experience forward.