Contract Definition and Stability

In my first zVision presentation that was recently given at each of the SRS offices, I identified one of Engineering’s current problems as an “absence of trust” between teams. This phrase caused some confusion that I would like to clarify.

Let’s say I want to write an app that integrates with the bookmarking service. My application will be reliant on their public API. So, for this venture to be successful:

The API’s Contract Definition is essential:

  • Method descriptions, examples, limitations and assumptions are all necessary and are included as part of the API documentation.

The API’s Contract Stability is essential:

  • Breaking changes should be very rare. Even with a disclaimer stating that it may change at any time, there is an implied level of stability in any published API.
  • When a breaking change to the API is necessary, backwards compatibility will be provided. That’s why their APIs all have “v1” in them!

Within SRS we should think about cross-project integration similarly to integrating with external services like Except in very rare situations, touch points between products are limited to APIs (i.e. massively-versioned web services).

When I referred to “absence of trust” in zVision, I call attention to the fact that we do not yet have the requisite level of Contract Definition and Contract Stability in our APIs. Without both definition and stability, I could not trust the API enough to base my app on it. The same is true for building on SRS-internally produced services.

Since the end of 2010 and through 2012 we are making a large investment in re-architecting our products based on principles of SOA and SaaS. Absolutely essential to success are APIs which are both well defined and stable. Once we have those things, we can trust the services provided by other SRS teams as much as we would trust

One thought on “Contract Definition and Stability”

Comments are closed.