TECH NEWS

Pact broker: the missing piece of your Consumer-Driven Contract approach (Part 3/3)

By Yoan Thirion, Agile coach and Craftsman at Agile Partner, in collaboration with Wilfried Vandenberghe.

November 28, 2019

The Pact Broker is an application for sharing for consumer driven contracts and verification results.

It is optimized for use with “pacts” (contracts created by the Pact framework), but can be used for any type of contract that can be serialized to JSON.

 

 

Let’s deep dive into the functionalities offered by the broker :

 

A RESTful APIfor publishing and retrieving pacts

The question that you can ask yourself when you start a CDC approach is where do I store the contracts ? In the consumer repository ? in a dedicated repository for the contracts ? in external libraries ? Where ?

The broker has been implemented to solve this question. The only source of truth is the broker where I can :

  • Publish a contract

  • Retrieve a contract

 

An embedded API browser for navigating the API

The Pact Broker API uses HAL (Hypertext Application Language) as its hypermedia implementation (that is, the method of providing links within a resource to navigate from that resource to related resources).

The Broker comes with an embedded HAL browser that lets you navigate the API in your browser window by using the HAL relations in each resource.

The HAL specification also provides a built in method for providing documentation about a relation. You can navigate to this documentation in the HAL browser by clicking on the book icon next to that relation in the HAL browser.

 

 

Displays provider verification results

When a pact is verified against a provider, the outcome of that verification (pass or fail) needs to be made available to the consumer and provider teams, so they know whether or not the code in either project can be safely deployed.

The pact verification tool can automatically publish the verification results back to the broker, and they will be displayed on the index page next to the pact details.

By displaying verification results you know if you can deploy safely.

 

Auto-generated documentation for each contract

A human readable version of the pact can be browsed from the broker:

 

Provides a “matrix” of compatible consumer and provider versions

When publishing a pact or a verification, the resource is associated with a particular version of the pacticipant (application), which is identified by a version number.

A pacticipant version number:

  • is expected to change (almost) every time a pact is published
  • should uniquely identify or be able to be mapped back to the commit of the code base that published a pact or verification (so that you can use tags to identify and checkout the the prodversion of your provider if you wish to test the “matrix”.)
  • should exist only on one branch of your code
  • should be known at release time (so you can pass it in to can-i-deployto ensure that you are safe to release)

 

Visualize your microservices

Dynamically generated network diagrams so you can visualise your microservice network.

 

A CLI for your CI/CD

 

CLI for encorporating the Pact workflow into your continuous integration process.

By using the can-i-deploy feature of the Pact Broker CLI, it will give you a definitive answer if the version of your consumer that is being deployed, is compatible with all of its providers.

This functionality can definitely save your life by avoiding an integration problem to arrive in production.

 

 

Docker pact broker

 

There is an official image for the broker available here : https://hub.docker.com/r/pactfoundation/pact-broker/

So it is really easy to setup and play with it with just a few lines of YAML:

Webhooks

Provides webhooks to trigger actions when pacts change eg. run provider build, notify a Slack channel.

You can trigger a webhook for those events:

 

To create a new webhook you just need to POST it to your broker:

 

In the broker you will have feedback on it:

 

 

To conclude those articles I would like to say that Pact and Pact broker together are really great tools BUT I would like to remind that consumer-driven contract testing is a technique that requires no special tool to implement. If you want to start without tooling go ahead, tools are just there to support the approach.

 

Once again it is all about communication.

Communication between teams :

  • Team that will need to consume a service
  • Team that will provide the service

 

 

Watch video

In the same category