Consumer driven contracts

Last week I attended a 5 day conference in Austin Texas learning all things open source and attending some great talk and tutorials, Oscon is the largest open source conference in the world and attended by thousands of developers, CTO’s and IT managers to further develop their knowledge and skill set. 

After a 10hr flight, I thought I would stretch my legs and see the sites of Texas’s capital. However, this was a bad decision after getting caught in a thunderstorm and having a 40min walk back to the hotel in the rain.


The 3rd talk of the first day was on transitioning to micro services (http://conferences.oreilly.com/oscon/open-source-us/public/schedule/detail/49952), a hot trend in the tech industry today and the lecture hall was fully packed. A very interesting subject that was discussed was ‘Consumer driven contracts’. 

Having recently completed a project building a SOA micro service platform in Quidco and now having that platform being used in Shoop.fr we have faced issues with the website or the admin having functionality impacted when there has been a change made within the platform, wanting to release continuously and freely. I felt after listing to the talk that 'consumer driven contracts’ will be an efficient approach for the platform team to check against before releasing any changeS. 


Consumer-driven contracts (CDC) is a pattern for specifying and verifying interactions between different parts/modules of an application. Consumer-driven means that it is the responsibility of the Consumer to specify what interactions it is relying on, as well as their format. Other services must then agree to these contracts and ensure that they are not breaking them. It puts the responsibility on the consumer of the service e.g. in Quidco’s example the team who built and manage the admin and site, to define the coverage and write tests for the platform team to run after they make a change, if the tests pass then the platform team can proceed on pushing these changes out, if the tests fail then they need to fix the failure before proceeding, however, when there are changes in the admin or front-end (consumer), the tests written need to be updated and maintained.  

Without the necessary precautions, there are a lot of ways interactions between services and consumers can be broken by changes made in the different services. The most common one would be that the Provider would change its interface in such a way that the Consumer can no longer interact with it


  • Change of the endpoint URL (e.g. GET /stockLevels renamed to GET /stockLevel)
  • Change in the expected parameters (e.g. GET /stockLevels expecting a new mandatory “category” field)
  • Change in the response payload (returns an array, instead of having an array wrapped in an object)

The concept behind CDCs is to split the work of the integration tests right in the middle, i.e. at the communication stage between the 2 services.

  • The consumer defines what it expects from a specific request to a service
  • The provider and the consumer agree on this contract
  • The provider continuously verifies that the contract is fulfilled

This implies a few things:

  • Consumers need a way to define and publish contracts
  • Providers need to know about these contracts and validate them
  • Consumers and provider might have to agree on some form of common state (if the provider is not stateless or depends on other services)

Since learning about CDC I have shared this with Quidco frontend lead, telling him about how CDC can reduce the reliance of heavy end-to-end or large-scale integration testing, within the conference I was told about Pact and this being a great tool for implementing CDC (https://github.com/realestate-com-au/pact). 


Sean Harrison