Designing Remote Service APIs

I’ve been meaning to bring an ongoing discussion about remote API design to this forum. A recent post to the Caucho hessian-interest mailing list prompted me to write a response that I am essentially reposting here.

The question at hand is what is the best approach for designing, publishing and versioning remote service APIs. 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 SOAP/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 internal 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 in their remote APIs. They expose an object model in their APIs that is explicitly designed for remote use.

To manage versioning Salesforce makes 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 versioning 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, if you want to support multiple versions. 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. 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 they 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.

I’m very interested to hear what others have to say on this topic.