Service APIs Client-Service Interactions Request and Response Management Service Implementation Service Infrastructures Service Evolution

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.
Consumer-Driven Contract: 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.