Publish Contracts

Allowed methods: POST

Path: /contracts/publish

Index relation: pb:publish-contracts

Supported from: v2.86.0

This is the preferred endpoint with which to publish contracts (previously, contracts were published using multiple calls to different endpoints to create the tag and contract resources). To detect whether this endpoint exists in a particular version of the Pact Broker, make a request to the index resource, and locate the pb:publish-contracts relation. Do a POST to the href specified for that relation.

The previous tag and pact endpoints are still supported, however, future features that build on this endpoint may not be able to be backported into those endpoints.

This endpoint is designed to be used by a command line tool, and hence, the response notices are designed for output to the user in a terminal.

Parameters

Responses

Success

The _links section will contain links to all the resources created by the publication. The relations are:

Errors

Schema validation errors

Any validation errors will be returned in the standard Pact Broker format with a 400 status:

{
  "errors": {
    "<fieldName>": ["message 1", "message 2"]
  }
}

Contract conflict errors

If there is a conflict with an existing published pact and allow_dangerous_contract_modification is set to false, a 409 will be returned with an array of notices, which will contain a diff between the existing pact content and the content that was attempted to be published. For consistency with the existing error responses, the errors hash will also contain the error messages, but there will be no diff included. For CLI usage, when there are notices and errors, just the notices should be displayed to the user.

{
    "notices":
    [
        {
            "text": "Cannot change the content of the pact for Foo version 183a77b0 and provider Bar, as race conditions will cause unreliable results for can-i-deploy. Each pact must be published with a unique consumer version number. For more information see https://docs.pact.io/go/versioning",
            "type": "error"
        },
        {
            "text": "<the diff, will include new lines>",
            "type": "info"
        }
    ],
    "errors":
    {
        "content":
        [
            "Cannot change the content of the pact for Foo version 183a77b0 and provider Bar, as race conditions will cause unreliable results for can-i-deploy. Each pact must be published with a unique consumer version number. For more information see https://docs.pact.io/go/versioning"
        ]
    }
}

Example

POST http://broker/contracts/publish
{
  "pacticipantName": "Foo",
  "pacticipantVersionNumber": "dc5eb529230038a4673b8c971395bd2922d8b240",
  "branch": "main",
  "tags": ["main"],
  "buildUrl": "https://ci/builds/1234",
  "contracts": [
    {
      "consumerName": "Foo",
      "providerName": "Bar",
      "specification": "pact",
      "contentType": "application/json",
      "content": "<base64 encoded JSON pact>"
    }
  ]
}

{
  {
    "notices": [
      {
        "type": "debug",
        "text": "Created Foo version dc5eb529230038a4673b8c971395bd2922d8b240 with branch main and tags main"
      },
      {
        "type": "info",
        "text": "Pact published for Foo version dc5eb529230038a4673b8c971395bd2922d8b240 and provider Bar."
      },
      {
        "type": "debug",
        "text": "  Events detected: contract_published, contract_content_changed (first time any pact published for this consumer with consumer version tagged main)"
      },
      {
        "type": "debug",
        "text": "  Webhook \"foo webhook\" triggered for event contract_content_changed.\n    See logs at http://example.org/triggered-webhooks/1234/logs\""
      }
    ],
    "_embedded": {
      "pacticipant": {
        "name": "Foo",
        "_links": {
          "self": {
            "href": "http://example.org/pacticipants/Foo"
          }
        }
      },
      "version": {
        "number": "1",
        "branch": "main",
        "buildUrl": "http://ci/builds/1234",
        "_links": {
          "self": {
            "title": "Version",
            "name": "dc5eb529230038a4673b8c971395bd2922d8b240",
            "href": "http://example.org/pacticipants/Foo/versions/dc5eb529230038a4673b8c971395bd2922d8b240"
          }
        }
      }
    },
    "_links": {
      "pb:pacticipant": {
        "title": "Pacticipant",
        "name": "Foo",
        "href": "http://example.org/pacticipants/Foo"
      },
      "pb:pacticipant-version": {
        "title": "Pacticipant version",
        "name": "1",
        "href": "http://example.org/pacticipants/Foo/versions/dc5eb529230038a4673b8c971395bd2922d8b240"
      },
      "pb:pacticipant-version-tags": [
        {
          "title": "Tag",
          "name": "a",
          "href": "http://example.org/pacticipants/Foo/versions/dc5eb529230038a4673b8c971395bd2922d8b240/tags/a"
        },
        {
          "title": "Tag",
          "name": "b",
          "href": "http://example.org/pacticipants/Foo/versions/dc5eb529230038a4673b8c971395bd2922d8b240/tags/b"
        }
      ],
      "pb:contracts": [
        {
          "title": "Pact",
          "name": "Pact between Foo (dc5eb529230038a4673b8c971395bd2922d8b240) and Bar",
          "href": "http://example.org/pacts/provider/Bar/consumer/Foo/version/dc5eb529230038a4673b8c971395bd2922d8b240"
        }
      ]
    }
  }
}