Creating a client for RESTful service

Question

When building RESTful services, I always come up against the issue of how to develop a client library that can distribute to users of the system.

To take a simple example, say there is a entity call person, and you want to support the basic CRUD functionality through your RESTFul service.

• To save a person, the client needs call POST method and pass the appropriate data structure, say in JSON.

• To find people by birthday, your service will reply with a response containing a list of people objects

• To delete an person, your service will respond with a success or failure message.

From the above examples, there are already two objects that may be shared with the client: the person object and the response object. I have tried a few ways of accomplishing this:

1. Including the Person object from your server call in the client library. The downside to this approach are:

   • The client code become tightly coupled with your server code. Any changes from server side will require client to make update during the same release.

   • Person's object may contain dependencies or annotation used for persistence or serialization. The client cares nothing about this
     libraries but are forced to include them.

2. Include a sub class of Map which is not directly tight to Person's object but contains some helper classes to set required fields.

   • Looser coupling, but could result in silent errors when data structure from server changes.
3. Use a descriptive file like Apache Thrift , WADL or Json Schema to generate client objects during compilation time. this solve the issue of object dependencies but still creates a hard dependency. This is almost like creating a WSDL for SOAP. However, this approach is not widely used and some times difficult to find examples.

What's the best way to publish a client jar for your application, so that

1. Its easy for client to use
2. Does not create tight coupling and some tolerance for server side changes

If you answer is better documentation of the API, what's is a good tool to generate these documents from Java annotation and POJOs.

Answer 1

This is a common problem, regardless of the protocol used for communication.

In some of the REST APIs we've been working with recently (JAX-RS based), we create DTO objects. These are just dumb POJOs (with some additional annotations for JAXB to do some marshalling/unmarshalling for us automatically). We build these as a submodule (in maven) and provide them as a JAR so that any other projects using our API can use the DTOs if they wish. Obviously, if you want to provide your own client library, it can make use of these DTOs. Having them provided as a separate JAR (which any app can depend on) means clients aren't pulling in crazy dependencies that they don't need (your whole serverside code).

This keeps things fairly well decoupled.

On the other hand, you really don't need to provide a client. It's REST after all. Provided your REST API is well constructed and follows HATEOAS principles, your API should be easily crawlable/browsable, ie you shouldn't need any other descriptive scheme. If you need WADLs or other similar constructs, your API probably isn't very RESTful.