Restful architecture issue with (too many) complex objects

Alright, I've been put in charge of both the server and client (used internally) part of this RESTful architecture. (using restlet).

We've got a resource that exposes the Post operation. Here's a simplified version:

public class UserResource {

    @Post
    public Representation create(UserRegistration registration) {
        SomeService.getInstance().createUser(registration);
        return new XstreamRepresentation(new RegistrationResponse(registration.getUniqueCode()););
    }

For a few months, we've been the only ones using these services, so domain objects were shared across client and server sides... and it's been working just fine.

Now that we have to document these resources and let other clients use them some "issues" have been arising that made me think this API might be a little too complicat开发者_StackOverflowed.

This Post service, for example. The internal method accepts complex type UserRegistration

public class UserRegistration implements Serializable {

    private Profile profile;
    private Boolean someBooleanProperty;

    public UserRegistration(Profile profile) {
        this(profile, true);
    }

    public Profile getProfile() {
        return profile;
    }

    public boolean isSomeBooleanProperty() {
        return someBooleanProperty;
    }

}

which, in turn, uses another complex object (Profile)

public class Profile {

    private String nickname;
    private String email;
    private String password;
    private String firstname;
    private String lastname;
    private Date birthDate;
    private String phone;
    private Address address;
    private GenderType gender;
    private String subscriptionSite;
    private Date privacyAcceptanceDate;
    private Date subscriptionDate;
    private String activationCode;
    private String socialSecurityNumber;
    ...

which is using a lot of complex types and so on.

This use of complex types is what really bugs me. I either don't know how to document this (apart from making a long long list of these complex objects inner properties) or I'm just lost.

My questions are: Do I have to simplify? Is this architecture very bad-designed? Would a few builder methods do the trick?

---

By sharing domain entity types between the client and the server, you (not saying you specifically) have completely defeated the point of REST. RESTful systems are supposed to share only media types and link relations. Sharing types like you are doing is much easier with SOAP because WSDL allows toolkits to take care of the details of keeping the client and server types in sync.

REST is all about reducing the coupling between client and server to allow them to evolve independently. Obviously, if you have a large set of shared types, that is going to be difficult, which why you currently have this bad feeling.

The solution I have taken to this problem is to define two media types. One is sort of a generic entity data container. Let's call it BusinessDocument, and the other is called BusinessLayout. The client uses the BusinessDocument to retrieve all the data from the server and the BusinessLayout provides "data binding" information so the client knows where in my UI to display the different pieces of business data.

By doing this I am able to build a client that really doesn't understand the specifics of the data it is dealing with, it just knows how to display it on the UI for the user to interact with. By doing this, I am able to use a single media type, to describe hundreds of different business entities.

---

There's no need to give the java client to external consumers. Your API should be able to answer to any Http client. The fact that there is a java client that shares the object can depend on different factors but should not influence how you expose your REST API to third party consumer.

So I'd suggest to start writing a pure HTTP client, using apache commons HTTP, to see how your REST API behaves.

The fact that the server objects are complex also should not be of any interest of the API. If the old system was designed modeling object around data, which I consider a bad idea, that's something you have to deal with. From the REST API you always receive just text, XML or JSON, and you have eventually to parse it into your Java Object, if you have for example and ORM + RDBMS backed system. If you could store Json, like on a a document DB, you do not have this problem but, again, this is of no concern of the REST API per se, but you need a layer that transform JSON to Java Object.

Restlet helps you with this, of course such complicated object is not an easy one to be automagically converted.