Consumer-Driven Contracts
By Ian Robinson
A service has several clients, each with different needs.
Service owners know who their clients are, and client developers are able to communicate their expectations
of the service's API to service owners.
How can a web service API reflect its clients' needs while enabling evolution and avoiding breaking clients?
Service APIs must often evolve to meet the unique needs of different clients. However, whenever a service
changes to accommodate the requirements of a single client, the other client applications face the risk of
breaking changes. Some service developers have tried to skirt this problem by creating service APIs that attempt to
address all current and future client needs. More often than not, these efforts turn out to be futile as
missed requirements are identified, and unanticipated changes are requested.
Service owners who understand how clients use their APIs are at a great advantage.
They are able to create client-centric tests that identify when service changes cause clients to break.
However, when the service owner creates these tests, they are often an inaccurate interpretation of how the client
might use the services. Client owners can help service owners understand how their services will be used by
documenting their expectations, but unless these documents are generated from code and schemas,
and regenerated every time they change, they can quickly become out of date. What the parties really
need are a set of automated integration tests.
Client developers write integration tests that express the client's expectations of a service API. These tests are given to the service owner, who incorporates them into the service's test suite.
The Consumer-Driven Contract
pattern helps service owners create service APIs that reflect client needs;
it also helps service owners evolve services without breaking existing clients. Service owners receive
integration tests from each client and incorporate these tests into the service's test suite. The set of integration
tests received from all existing clients represents the service's aggregate obligations with respect to its client base.
The service owner is then free to change and evolve the service just so long as the existing integration tests continue to pass.