Bill Burke has just posted a bunch of really great feedback on the latest draft of the JAX-RS spec. If you haven’t had a chance to look at the spec, head over here. One thing that JSR-311 had initially chosen not to do was to define a client API. There has a been some grumblings about the lack of a client API in the spec. After readings Bill’s post, I’m starting to think there is a need for a client API in the spec.

There are a few reasons why a client API could make sense:

• You can reuse the same collection of EntityProviders on the client. They are already handle request/response anyway, so it’s a natural choice.
• Some of the annotations are applicable to client applications
• Utility classes like URIBuilder are useful to both sides of the API.

One of design decisions I made with RESTEasy was to separate the framework into three parts:

• A Client API
• A Service API (soon to be implementing JSR-311)
• And a collection of common code that is shared between both client and server

The RESTEasy common library handles thing like EntityProviders(aka RepresentationHandlers in the old RESTEasy), Header and Request info, and some other common utility classes.

What Bill suggested was to have the ability to place annotations on interface classes. This is what the current implementation of RESTEasy does with EJB3-based Resources. The cool thing that Bill is suggesting is that it would be then possible for the client API to do something like:

@Stateless
public class PeopleResourceBean {	
    public Person getPersonById(int id) {...}

}

Also note how the JAX-RS annotation don”t litter your bean class? 🙂 You can then annotate your local interface such that:

@Local
@UriTemplate("/people")
public class PeopleResource { 
  @UriTemplate("{id}")
  @HttpMethod("GET")
  public Person getPersonById(@UriParam("id") int id);
}

Then finally, you’re client code could do something like:

public class PeopleServiceClient {	

@HttpResourceRef("http://somehost.com") PeopleResource peopleResource;

public Person getPersonById(int id) {
 	return peopleResource.getPersonById(id);
}

}

The client side framework would the take care of implementing the business of connecting to the remote service. The @HttpResourceRef is just an idea at this point, but this will provide a means to define the root location of the service. Once the interface is injected, it reads the @UriTemplate annotations to access the resource.

I’m starting to think this could be a pretty cool thing to have in the spec, or at the very least in RESTEasy 1.0.