RE: best practices for complex objects

Your question is a great one and not one that I have seen addressed
well.

Through my experiences designing and programming against remote service
APIs I've come to develop the following opinion:

If you are developing remote APIs for a known and manageable set of
clients, exposing your fine grained object model through the API over a
mechanism like Hessian makes for rapid development and easy integration.
Being able to rev your object model and have the changes show up in the
API is a benefit in this case since you do not have to manage a
translation layer to DTOs, XML or something else.

If you are developing remote APIs for an unknown and unmanageable set of
clients, you need a layer between your server side object model and the
model exposed to the clients. This allows you to rev your internal model
while keeping the external interface consistent. Of course, you then
have to maintain the translation.

I have seen this second approach addressed well using SOAP by
Salesforce.com: http://www.sforce.com/resources/api.jsp. In the case of
Salesforce, they make different WSDL available for different versions of
the API. Using different WSDL gives you access to different versions of
the service. I'm not sure of the mechanism but it could be either
contained in the SOAP session that you establish with Salesforce or
simply be a different end point for accessing the service.

Different end points for different versions seems like one good way to
manage versioning your services. Clients opt in to a version by choosing
an end point.

I have also seen this second approach addressed well by Flickr in their
RESTful XML APIs: http://www.flickr.com/services/api/. Flickr does not
seem to have addressed versioning and simply has kept their APIs 'in
beta' to allow them to rev the APIs without supporting old versions.

The success of Flickr in getting the general developer community to use
their APIs has led me to the conclusion that if you want people to use
your APIs v. providing them because users are demanding them, then a
custom, well documented XML-over-HTTP API will be most successful.
Clients have to write more code but the code you have to write is
obvious by looking at the APIs.

If you use a SOAP/Hessian/Burlap implementation that will convert your
object model to a wire format for communication between server and
client, you then need to maintain an object model for your API
separately from your internal object model. I'm starting to think that
if you are maintaining a translation between an internal and public
model, you may as well have that public model be XML based. Remember,
I'm talking about the case where you a supporting an unknown and
unmanageable set of heterogeneous clients.

I'd prefer that developers of remote clients all wanted to use SOAP (or
Hessian or Burlap) but it just doesn't seem to be that way. In the
enterprise developer community, sure, but what about people writing
Flash and Javascript clients of which there are increasing numbers every
day.

> -----Original Message-----
> From: owner-hessian-interest@xxx.com [mailto:owner-hessian-
> interest@xxx.com] On Behalf Of Dan.B.Tanner@xxx.com
> Sent: Wednesday, July 13, 2005 7:47 AM
> To: hessian-interest@xxx.com
> Subject: best practices for complex objects
>
> I just wrote some hessian-based remote services in preparation for a
1.0
> release. One of them has the following signature:
> public com.foo.service.dto.UserInfoDto getUserInfo(String lanId)
>
> I'm hesitant about using a rich UserInfoDto object though, with the
> potential headaches of versioning it for multiple clients down the
road
> as it changes. i.e. If this goes out to 10 clients, and then I change
> it, I can't feasibly force my clients to switch their client code at
the
> same time.
>
> What options have others found successful and unsuccessful for this
kind
> of scenario? The alternatives I can think of are:
> 1. Return a Map filled with only the basic object types. This would
> seem to allow workarounds for most of the versioning issues, but it's
> not as intuitive or strongly typed.
>
> 2. Return an XML String. Similar to above, but it's not quite as
> convenient for the client.
>
> 3. Version my client and service by package name. e.g.
> com.foo.dto.service1_0.dto.UserInfoDto for the first release, and
> com.foo.dto.service2_0.dto.UserInfoDto for the 2nd release.
>
> Thanks for your thoughts,
> Dan
Received on Wed 13 Jul 2005 10:00:06 -0700