On Compiled Contract

I finally published compiled contract over at Web Cohesion. It's quite a formal document; I wanted to make sure I tied up all the loose ends. But I thought I'd take a more informal approach here.

The whole idea sprang from frustration with the only two Web service development models. Contract-first development was too painful, but code-first development suffered from a lack of interoperability (which is kind of the whole purpose for Web services in the first place).

The debate has been active for years. It seems to me that most people agree that in order to ensure interoperability, you need a contract-first approach. Until recently, I probably would have agreed with this. However, I think the latest tools and specifications in Web service development are pushing that position farther into doubt, as developers are better able to tweak the contract from source code.

But just because the developer can ensure interoperability, doesn't mean that he will, or even that he knows how. That's why I think a whole new Web service development model is needed. One that allows developers to write a Web service API in source code, but to not have to worry about interoperability.

Enter compiled contract. The developer can maintain the Web service API in source code, where the entry barrier is low, the learning curve is gentle, and where she can use her favorite IDE. But she doesn't have to know anything about WSDL, XML-Schema, or the WS-I Basic Profile because the contract is compiled and interoperability is enforced before any executables are even runnable.

This isn't a new concept. We've been working with compilers for years. Nobody who programs in Java, for example, has to know about the internals of Java bytecode. To impose that requirement in order to ensure interoperability between platforms would be ridiculous: the bytecode specification is too complex and esoteric.

By the same token, Web service developers shouldn't be required to understand the details of WSDL: it's too complex and esoteric. There is no reason why the knowledge of the heavy Web service specifications couldn't be consolidated with the few of us who are masochistic enough to specialize in them, much the same way that knowledge of bytecode is specialized with the people who write compilers.

Well, as I'm almost ready to cut an open source release of the first contract compiler, I can say with confidence that compiled contract is more than just a good theory. It really works. It ensures interoperability better than contract-first, and it streamlines the development process better than code-first.

I'm really excited about it.

Leave the REST to SOAP

Does being a SOAP advocate make me a REST detractor? I don't think it does. I like REST. There are a lot of advantages to it. It's based on proven, solid principles and technologies and it encourages good design by enforcing clarity and simplicity. I'd even go so far as to say that REST should be the first choice when deciding the technology for your web API. But the more complex your service model becomes, the easier it is for REST to backfire and the more likely it is that SOAP is a better choice.

There are two things that bother me about die-hard REST fanaticism. The first is the (often implicit) allegation that REST will solve your complexity problem and SOAP will make it worse. Whether you use SOAP or REST, you must start with a clean service model in order to end with a clean service model.

The second thing that bothers me about REST fanaticism is the assumption that REST is right for all service models. Oh... except the "wrong" ones. So if my service model doesn't fit into a RESTful paradigm, some restafarians would tell me the problem lies with my service model. Now, I can respect the architectural principles of REST and try to apply them in my design, but let me be the expert on my own problem space. Don't try to tell me what my service model should be.

I'm going to suggest some possible disadvantages to REST in an attempt to better understand when REST might not be a good choice:

The first disadvantage is that REST doesn't fit all service models. Sure, it fits a lot of them. You might even be able to convince me that it fits most of them. But what about stateful service models? What about service models that support a rich, complex data model? What about multi-step or transactional service models? I admit that REST could be stretched to support any one of these, but I think it starts to break down. And I don't think REST should be used to support two or more of these.

I often hear cited Amazon's statistic that 85% of its web API usage is of the REST interface. I'm neither surprised nor impressed. I'd guess that 85% of the API usage is limited to search/read operations and that most of the create and update operations are done with its SOAP API. And Amazon is not the only company that is generally a read operation. Google, Yahoo, Flickr, all of these have wisely chosen REST because their service models are limited generally to simple and atomic operations.

The second disadvantage is that REST doesn't explicitly define the service model it exposes. REST limits the vocabulary for describing your service model to XML and four verbs (create, read, update, delete). Many service models fit nicely into this vocabulary, and others can be compressed to fit. But a service model can only be compressed a limited amount before it experiences data loss.

When a service model is published using REST, the consumers of the API have to do a certain amount of interpretation to use it. This leaves room for ambiguity and bad assumptions. Using HTTP and XML lowers the entry barrier, but each developer might have to make their own assumptions on things like the subtle differences between "PUT" and "POST" and how to interpret and empty XML element. Some service models are simple enough that differences in interpretation are insignificant, but more complex service models will have to put much more effort into communicating to developers the subtleties of their API.

3. Finally, REST has no widely-adopted specifications (like WSDL) to use for defining the API. Programmers have to swallow raw XML because of the lack of tools and IDEs that rely on formal specifications. Documentation for a RESTful API is limited to human-readable text. Once again, the simple, atomic service models can more easily live with these limitations than can the more complex stateful models.

So don't be discouraged if your service model doesn't fit very well onto a RESTful paradigm. You're not alone, and it doesn't necessarily mean there's anything wrong with your design. Do what you can, and leave the REST to SOAP.

How to Tame XML-Schema for OO Programming Languages

Yesterday I wrote about complexity required to map Java grammar to XML-Schema. I looked a bit more into the work that's been done, and noticed that the WS-I apparently started to take on establishing a profile for XML-Schema but it never panned out.

I don't know. I'm not completely convinced that there isn't a way to establish a standardized mechanism for mapping XML-Schema onto an OO programming grammar.

Knowing (at least for web services) that the schema is probably generated from a set of classes, I wonder if there could be a standardized set of schema annotations that indicate what the classes looked like from which the XML-Schema derives. Then, the consumers of the web service would have some hints on how to be reflect the original package/class/method structure.

XML-Schema and Object-Oriented Programming Grammars

I've recently been trying to digest the JAXB 2.0 specification and I've been amazed at the complexity that is needed to support the XML-Schema paradigm from Java. And although I'm not familiar with the way XML-Schema is supported in other OO languages, I'd be surprised if it isn't just as complex.

I appreciate XML-Schema. I think the W3C did an excellent job defining it clearly, but to claim it to be simple would be specious. I wonder if there isn't some way to define a subset of XML-Schema features that map more readily and concisely onto an object-oriented paradigm, much like what the WS-I Basic Profile did for WSDL.

Having a high degree of flexibility in XML-Schema is great, but when it gets down to the practical application, certain features rarely get used because, in the end, the instance documents have to be consumed by by a real programming language.

APT-Jelly Released

So I finally got around to cutting release 1.0 of APT-Jelly. I posted a news item on TheServerSide and got some good feedback. Hopefully, I'll get around soon to more directly supporting Velocity and Freemarker templates.

Digesting the APT Mirror API

I've been trying to write a Jelly tag library that can be used to write templates for generated output and generated java source files with Sun's new annotation processing tool (APT). (See my submission to the jakarta-commons mail list.) It's going quite well, thanks to the smart people who architected Jelly.

It's also been educational for me to try to digest the APT Mirror API because I've had to learn more about the formal Java 5 language syntax definitions (e.g. generics, annotations, etc). Before today, I had no idea what erasure was, except that it was a concept introduced with generics. This tutorial helped explain a lot about generics and the terms used to describe the syntax structures like "formal type parameters" and "bounded wildcards," as well as terms like erasure. I once tried to use the new reflection API to attempt to reflect on a formal type parameter, but I found that I couldn't swallow it, and I had to back down in fear. Maybe I'll have another go.

So, back to finishing up the new Jelly tag libarary.... It should go a lot faster now that I have a better understanding of the API for which I'm providing an XML interface. I'm going to go through the XDoclet Template Language as a reference for what functions may be needed. I like XDoclet. I really do. But thank goodness I won't have to digest that awful template language syntax anymore!

Bootstrap

So I thought I'd start a blog. I hope I have something to contribute to my areas of interest. We'll see....

Nothing ventured nothing gained.