BBC Consumer Contracts

What BBC Consumer Contracts is

BBC Consumer Contracts is a JavaScript package for defining and running consumer-driven checks against APIs. A contract records a consumer, a name, a request, and the response that consumer expects. When executed, it makes an HTTP request with the request package and checks the result with Joi. Checks can cover the response status code, headers, and JSON body, with Joi schemas describing the expected body. This lets a project verify that an API response matches the needs expressed by its consumers.

Contracts can include optional before and after functions for setup and cleanup. Those functions can use callbacks or asynchronous behavior. Retry settings accept a number or a custom option; the documented maximum retry default is zero. The command line tool can run all contracts recursively in a contracts directory or execute one contract file. Code can instead call validateContracts with an array; it processes every contract in that array rather than stopping after the first failure.

The package supports consumer verification and self-hosted deployment. It is free, with the Consumer Contracts plan priced at $0. Runtime requirements are Node.js 18 or later and pnpm 10 or later. The project is licensed under Apache License 2.0; the BBC can be contacted about an alternative licence.

Who it suits

It suits JavaScript teams that need executable API contracts to check whether responses meet consumer expectations. Teams can run checks through the command line or call the package from code, and can host it themselves.

Getting started

1. Use a Node.js 18-or-later environment with pnpm 10 or later.
2. Install the package globally for command-line use or locally as a development dependency with pnpm.
3. Define a JavaScript contract with consumer, name, request, and response properties.
4. Run the CLI against a contracts directory or a single contract file, or call validateContracts with an array.

Verdict

Choose BBC Consumer Contracts if you need a free, self-hosted way to express consumer expectations as executable JavaScript API checks. Its request and Joi integrations cover response codes, headers, and JSON bodies, with both command-line and programmatic execution. Consider another option if your runtime does not meet the Node.js and pnpm requirements or you need a non-JavaScript contract format.