Pactflow/Pact broker API Reference Documentation

You can find the API documentation of Pactflow resp. Pact broker server under the following address:

https://your_company.pactflow.io/hal-browser/browser.html

Usage examples

The explorer

The API methods and their documentation can be found here:

https://your_company.pactflow.io/hal-browser/browser.html

On this page, you have the field [Explorer]. The URL entered here shows the commands that can be used in the corresponding context:

In the above screenshot, we have the https://your_company.pactflow.io in the [Explorer] field, so the commands shown are the general top-level commands.

To see the commands that are applicable to different contexts, you can enter corresponding URLs in the [Explorer] field and each time click on [Go!]:

The following URL in [Explorer] field would list commands that are applicable in the context of participants that can be both providers or consumers:

https://your_company.pactflow.io/pacticipants/

The following URL in [Explorer] field would list commands that are applicable in the context of a specific participant e. g. a participant with the name “pactflow-example-bi-directional-provider-dotnet”:

https://your_company.pactflow.io/pacticipants/pactflow-example-bi-directional-provider-dotnet

Here is another example for a participant with the name “pactflow-example-bi-directional-consumer-dotnet”:

https://your_company.pactflow.io/pacticipants/pactflow-example-bi-directional-consumer-dotnet

The following URL in [Explorer] field would list commands that applicable in the context of pacts for a specific provider e.g. a provider with the name “pactflow-example-bi-directional-provider-dotnet”:

https://your_company.pactflow.io/pacticipants/pactflow-example-bi-directional-provider-dotnet

Of course you don’t have to browse through the API by entering different URLs manually in the [Explorer] field. For example the URL https://your_company.pactflow.io/pacticipants/ (3) is automatically loaded into the [Explorer] field if we start with the URL https://your_company.pactflow.io (1) in the [Explorer] field and then click on the command pb:participants (2):

Environment methods

Getting the list of environments

The environments can be found here in Pactflow GUI:

To see how you can get a list of the environments shown above using an API request open the Pactflow documentation page on your instance by navigating to the following address:

https://your_company.pactflow.io/hal-browser/browser.html

Click on the following symbol:

Scroll the browser page upwards to see the page that should have opened after you have clicked on the symbol mentioned before, otherwise, you may not realize that a new page is shown as it happened to me. Now you can see the instructions on how to list the environments or how to create a new environment:

To list the environments configured in the Pactflow server you can execute the following curl command:

curl -X GET \
  https://your_company.pactflow.io/environments \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Creating a new environment

To create a new environment you can use the following command:

curl https://your_company.pactflow.io/environments \
  -H "Content-Type: application/json" \
  -H "Accept: application/hal+json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
      "name": "test1",
      "displayName": "Test1",
      "production": false
    }'

The token passed to the command can be found on the Pactflow GUI on the following page:

Deleting an environment

Once you start to create an environment, you might start to feel the need to find a way to delete them once you no longer need them. To achieve this you can use the following command:

curl -X DELETE https://your_company.pactflow.io/environments/c99aa632-3d56-4e10-b1b5-0282ccc3673f \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Get the list of environment names:

You can use the jq command (see Simple jq command examples) to retrieve selected data from the JSON content returned by the curl command. For example, the following command returns the list of environment names:

curl -s -X GET \
  https://your_company.pactflow.io/environments \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' | jq '.["_embedded"]["environments"] | .[].name'

The result could for example look like this:

"production"
"test"

Get an environment object by its name:

The following bash script would allow us to retrieve an entire environment object with all its properties (see the output further below) by using its name for selection:

#!/bin/bash

name="production"

curl -s -X GET \
  https://littleitkb.pactflow.io/environments \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' | jq -r --arg name "$name" '._embedded.environments[] | select(.name == $name)' -

The result of the script above would be one environment object (if an environment with the passed name does actually exist):

{
  "uuid": "06e8f356-aa88-45a0-aa6f-5ad6d7a759f5",
  "name": "production",
  "displayName": "Production",
  "production": true,
  "createdAt": "2022-07-22T23:37:47+00:00",
  "_links": {
    "self": {
      "title": "Environment",
      "name": "production",
      "href": "https://littleitkb.pactflow.io/environments/06e8f356-aa88-45a0-aa6f-5ad6d7a759f5"
    },
    "pb:currently-deployed-deployed-versions": {
      "title": "Versions currently deployed to Production environment",
      "href": "https://littleitkb.pactflow.io/environments/06e8f356-aa88-45a0-aa6f-5ad6d7a759f5/deployed-versions/currently-deployed"
    },
    "pb:currently-supported-released-versions": {
      "title": "Versions released and supported in Production environment",
      "href": "https://littleitkb.pactflow.io/environments/06e8f356-aa88-45a0-aa6f-5ad6d7a759f5/released-versions/currently-supported"
    },
    "pb:environments": {
      "title": "Environments",
      "href": "https://littleitkb.pactflow.io/environments"
    }
  }
}

Getting the environment Id by its name

In the following example, we first get an environment object by its name and then get from that environment object the Id:

#!/bin/bash

name="production"

curl -s -X GET \
  https://littleitkb.pactflow.io/environments \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_API_TOKEN' | jq -r --arg name "$name" '._embedded.environments[] | select(.name == $name) | .uuid' -

The output of this script would be just a GUID value provided that an environment with that name would exist on Pactflow:

06e8f356-aa88-45a0-aa6f-5ad6d7a759f5

Mixed examples

Publishing a pact

To publish a pact file we can use the pb:publish-pact API method. Let’s use the GUI to send the publishing query:

The [Make a NON-GET request] dialog appears. Here are example values for the fields:

Target URL: https://littleitkb.pactflow.io/pacts/provider/pactflow-example-bi-directional-provider-dotnet/consumer/pactflow-example-bi-directional-consumer-dotnet/version/9b89b51a-5099-4e5d-a332-a04f2def1ee7

Method: PUT

Headers: Leave it as it is

Body: Copy/paste the entire content of a valid pact file, e. g. the pact from the official pact example here: https://github.com/pactflow/example-bi-directional-consumer-dotnet

After this request, if successful, you will see a new pact interaction (if you start from an empty fresh state) on the Pactflow GUI:

Getting the latest pact published with a given branch name

Publish two or more different pacts (change the build version to have different pact versions published), e.g. by using a script like the below example (also make sure to have a valid pact file in the pacts folder):

#!/bin/bash

DOCKER_BUILDKIT=0 docker pull pactfoundation/pact-cli:latest

BrokerBaseUrl='https://your_pact_account.pactflow.io/'
BROKER_RW_TOKEN='**********************'
BuildSourceVersion=bea26111-a432-4688-a6de-fba711ef3b09
BuildSourceBranchName='master'
BuildBuildUri='https://your_pact_account.pactflow.io/'

docker run --rm -v ${PWD}:${PWD} pactfoundation/pact-cli publish ${PWD}/pacts -b "$BrokerBaseUrl" -k "$BROKER_RW_TOKEN" --consumer-app-version "$BuildSourceVersion" --auto-detect-version-properties --branch "$BuildSourceBranchName" --build-url "$BuildBuildUri"

Assuming you would have started to publish the two pact files with different versions from a fresh and empty starting point your pacts would look something like this (in the [MATRIX] view):

Now we would like to use the API to get the latest of these two pact files.

Click on the GET method of the pb:latest-pact-version API method:

In the resulting response you can then find the version of the pact you published at last:

 ...
 "createdAt": "2023-05-12T14:35:11+00:00",
  "_links": {
    "self": {
      "title": "Pact",
      "name": "Pact between pactflow-example-bi-directional-consumer-dotnet (81172906-0d5d-469c-aeb7-d06b360398fb) and pactflow-example-bi-directional-provider-dotnet",
      "href": "https://littleitkb.pactflow.io/pacts/provider/pactflow-example-bi-directional-provider-dotnet/consumer/pactflow-example-bi-directional-consumer-dotnet/version/81172906-0d5d-469c-aeb7-d06b360398fb"
    },
    "pb:consumer": {
      "title": "Consumer",
      "name": "pactflow-example-bi-directional-consumer-dotnet",
      "href": "https://littleitkb.pactflow.io/pacticipants/pactflow-example-bi-directional-consumer-dotnet"
    },
    "pb:consumer-version": {
      "title": "Consumer version",
      "name": "81172906-0d5d-469c-aeb7-d06b360398fb",
      "href": "https://littleitkb.pactflow.io/pacticipants/pactflow-example-bi-directional-consumer-dotnet/versions/81172906-0d5d-469c-aeb7-d06b360398fb"
    },
...

Getting all versions of a participant

In this example, we try to get all versions of a participant (given by its name).

We can achieve this by the following curl command:

curl https://littleitkb.pactflow.io/pacticipants/pactflow-example-bi-directional-consumer-dotnet/versions \
  -H "Content-Type: application/json" \
  -H "Accept: application/hal+json" \
  -H "Authorization: Bearer ***************"

We can achieve the same using the API browser:

Enter the URL of the participant in the [Explorer] field and click on [Go!]:

https://littleitkb.pactflow.io/pacticipants/pactflow-example-bi-directional-consumer-dotnet/versions

We get a response that contains all the versions published for this pacticipant.

Getting all branches of a pacticipant

The following shell script shows one way to print out all branches of all pacts published for a pacticipant with a given name:

response=$(curl https://myapp.pactflow.io/pacticipants/pactflow-example-bi-directional-consumer-dotnet/versions \
  -H "Content-Type: application/json" \
  -H "Accept: application/hal+json" \
  -H "Authorization: Bearer ****************")

output=$(echo $response | jq '.["_embedded"].versions[]["_embedded"].branchVersions[].name')

for item in $output; do
    # Process each item here
    echo "$item"
done

Troubleshooting

The remote certificate is invalid according to the validation procedure

Problem

We have tried to send an API request to Pactflow using the PowerShell Invoke-RestMethod command, for example, a request like this:

$url = "https://my_pactflow_url/pacticipants/pactflow-example-bi-directional-consumer-dotnet/versions"
$headers = @{
    "Content-Type" = "application/json"
    "Accept" = "application/hal+json"
    "Authorization" = "Bearer *************"
}

$response = Invoke-RestMethod -Uri $url -Headers $headers

The command fails with the following error message:

The remote certificate is invalid according to the validation procedure.

Potential Resolution

It’s possible that your URL is wrong, take a close look at your URL.