One of my current projects involves creating a contract for a new web service-based API. We’re starting from scratch and developing a code-free1 contract2 prior to development. I’ve been involved, in one way or another, in the development of many web services and, of course, we never got too deep into the code without some broad understanding of what would be provided in the contract. The line between contract design and construction was much blurrier in most cases. We would start with some general understanding, someone would write some classes for the endpoint, everyone would start coding and stuff would get changed along the way.

All good fun, very agile, but, at the same time, not very close to contract-driven design - at least in theory.

When you stop and think about it, you realize that a heavy contract-first approach to building web services is very waterfally. It emphasizes documentation, process and the idea that a finished design can be sort of kicked down the hall to someone responsible for coding it up.

One colleague pointed out to me that the greatest success we had with sort-of contract first design came on one of our first projects together. I was doing user interface work and he was doing the backing web services. The architect on the product handed us a design he had sketched out. It wasn’t fleshed out or anything, but it represented a good starting point. We tweaked it a bit, filled in the gaps and started coding against it, each in a different language. The contract itself was an XSD document that was used to generate classes in Java and C# for the different components.

This sounds a lot like a contract-first paradise and, in that sense, I think contract-first has a lot to offer in terms of forging a basic consensus about what is going on. What differentiates that from a lot of contract-first theory is that we - the two who hammered out the final contract - sat next to each other throughout the project. We tweaked it to handle UI needs and to handle integration needs on the service side. We had a document of the contract, in the form of that little XSD, but it was a living contract.

I’m open, of course, to the idea that there is some selection bias here. It is all from my experience, which means that I was involved and my quirks and idiosyncrasies played out in each case. The most important thing is that I’m getting to try out something I don’t do as much and that’s a big part of what keeps us fresh. I look forward to doing something of a post-mortem on this project once it settles into production usage.

  1. A pedant would argue that, at some point, the contract that is used to generate classes is no different in the end than code written in Java or C# to create classes - but we none of us are pedants, are we? 

  2. The contract is in OpenAPI (Swagger) 3, a matter of future historical interest only.