APIs are the back-bone of modern software development. They allow you to separate the concerns of your app and allow for re-use across a range of platforms.
APIs also allow for others to build services around your products data, enabling an entire ecosystem to flourish around your product and increase your customer base indirectly.
Given that APIs are utilised by multiple platforms, some even outside of your direct control, it would stand to reason that the power balance of the API provider to API consumer lies heavily in favour of the API provider — this is incorrect.
If an API is unreliable or unusable then no-one will use it and much like any other product, if there’s no one buying then there’s no point selling. The contract between a provider and consumer is similar to real-life contracts, where if the provider fails to deliver on its promise the consumer can decide to end the contract and go elsewhere for its needs to be fulfilled.
A lot of API documentation tooling fails to realise this, instead utilising a top-down, provider centric model of API usage with the consumers being expected to ‘comply’ to the specification without any feedback loop to help providers understand what parts of the API are actually used.
If you’ve ever worked on a project with separate teams building an API provider and a consumer of that API, you’ve likely seen tools like this, usually a Swagger document, and you’ve likely seen that these documents rarely have the intended outcome with either the documentation being out of date or one or more parties not completely complying to the specification.
Empowering consumers
Consumer Driven contract testing tools such as Pact look to give the power back to the API consumers. This is achieved using a set of tests run on the consumer which define the request the consumer will make to the provider and the response it expects back. Essentially, it is the contract the consumer expects the provider to uphold.
This contract is then made available to the provider for it to ensure that when it receives the defined requests it responds accordingly. If the provider breaks the contract then the provider team can either make fixes to uphold the contract or they can work with the team building the consumer to ensure they’re aware of the breaking change.
Pact provides a tool to facilitate easier communication around a broken contract via the use of a broker, a server that sits between both parties and stores the contracts, and more importantly the status of whether each party honours the contract.
For API consumers this allows for quick feedback around the data they expect to get back from the provider, as they can see when the provider won’t be able to return the data it expects and they can either update their code or start a conversation with the team, working on the provider.
For API providers this allows for the team to see every downstream expectation on the data they provide, allowing them to get a better understanding of what data is not used or could be useful to provide, and through the broker they can run a test suite to ensure they meet the data needs of every consumer.
The broker can also be used to fire off tests when either party updates to ensure that everything will continue to work, and also provides a map of every consumer to provider contract allowing for teams to easily visualise dependencies.
Empowering Providers
The information on what endpoints and data consumers are using gives providers the flexibility to make changes without unexpected impacts, as they can run tests to verify that all contracts are upheld even if the change itself looks like a drastic change from the current model.
This information can also be used to better understand the needs of API consumers. If the companies business model is based around providing APIs then consumer driven contract testing provides valuable market research on what customers are actually doing with the API and what their future needs may be.
The combination of understanding user needs and flexibility means that the way APIs are built is vastly different to how things work with a top-down API specification, allowing for a more agile approach of iterating to find the data the consumer needs instead of telling them what you’ll provide.
The map that the Pact broker provides also allows API providers to see how widely their API is used, something that helps the team get a better understanding of the value they are providing.
The impact of consumer driven contracts
Consumer driven contracts can require some cultural changes to be made. If a team providing an API has been given a lot of political power because they’re supplying the data to run the consuming services, they might not be too happy being given a lot of new constraints in the form of contracts they need to honour.
If that team understands the benefit of fast feedback loops though, it should be easy for them to see how knowing what consumers actually use will make their lives easier in the long run.
This feedback doesn’t just apply to verifying contracts however and can be used in planning too. A simple spike to see the impact of changing what the API returns will reveal a lot about the dependent systems and aids cross-team working, as providers can add tickets to consumer backlogs to ensure they make plans to migrate to newer versions of the API.
Support and operation teams can also utilise the Pact brokers map of consumers and providers when planning infrastructure changes, as they can see how many downstream systems will be impacted by an outage of an API provider.
Solution Architects will also be able to use this map to determine what approach to take when the business has a new service to build, or if an existing system needs to be rebuilt to take advantage of better architectural approaches such as breaking a monolithic system into a set of microservices, which will likely result in more calls to API providers.
Summary
Consumer driven contracts aren’t just a tool for API consumers to use to tell API providers that they’ve broken their functionality but are a tool that can be used across roles and teams to empower people to make change.
By flipping the common power structure associated with services on its head consumer driven contracts allow for traceability across multiple teams and platforms and provide valuable information that can help build products as well as prevent defects.