Overview

The Pact Broker is a service for exchanging pacts and verification results.

The consumer CI build generates and publishes pacts. The provider CI retrieves and verifies the pacts, and publishes the verification results.

A pact is published using the consumer name, the provider name, and the consumer application version as an identifying key (PUT /pacts/provider/PROVIDER/consumer/CONSUMER/version/CONSUMER_APPLICATION_VERSION). The versioning of the pact content itself is done behind the scenes by the broker.

Consumer and provider applications are known as pacticipants (a bad pun which the pact broker author now regrets.) A pacticipant may be both a consumer and a provider. Pacticipants are automatically created when a pact is published for the first time. Pacticipant version resources are also automatically created.

When a pact is published, we know the provider, the consumer and the consumer version. We don't know the provider version until the pact is verified, and the verification results are published. A verification is published using the consumer name, the provider name, and the SHA of the pact version that was created for the pact by the broker. This means that if a new pact is published with exactly the same content as a previously verified one, it will automatically inherit the verification results of the existing content.

Tags are used to "bookmark" important versions of an application (known as a pacticipant in the API). They are generally used for identifying stages (eg. dev, staging, prod) or branches (eg. feat-some-new-thing) of your application. For example you might tag version 1.2.3+c6d6a4 of application Foo as the prod version (PUT /pacticipants/PACTICIPANT/versions/VERSION/tags/TAG. A version can have multiple tags. While tags belongs to application versions, they are mostly used for retrieving pacts. For example, you can retrieve the latest prod pact (GET /pacts/provider/PROVIDER/consumer/CONSUMER/latest/TAG)

TODO

Add explanation of can-i-deploy and webhooks.

WIP - advanced notes that need to be added somewhere

• Pacts and verifications should only be published from CI builds, not developer local machines.
• Note that if you publish a pact, the consumer, provider and consumer version resources are automatically created, however, if you delete a pact, they are not automatically deleted, so you may have orphan data lying around that will give you inconsistent results when you query the broker.