New all-in-one contract publishing endpoint

[bethesque]

At the moment, to publish a pact with tags and a branch or other information, multiple calls are required - one for each tag (has to be done first), one if there is a branch or build URL (to create the version resource) and one to create the pact.

Problems with this approach:

• There are ordering dependencies on the resources created
• There are multiple places for the publishing to fail.
• It requires the clients to navigate the HAL relations, or hardcode many URLs, and to have good knowledge of the internal modelling of the domain.

I would like to create a new, all in one, publishing endpoint. REST doesn't really make sense to me in this situation, as the call will create multiple resources, and there isn't really a good use case for keeping and returning all this data together, so I think just using an RPC style call would be more appropriate.

POST /contracts/publish
{
  consumerName: "Foo",
  consumerVersionNumber: "1",
  consumerVersionTags: ["a", "b"],
  consumerVersionBranch: "main",
  consumerVersionBuildUrl: "http://ci/builds/1234"
  contracts: [
      {
         provider: "Foo,
         contractType: "pact", //the only one supported for now,
         contentType: "application/json",
         content: "base64 encoded content"
      }
   ]
}

This would return a response that had links to all the created resources (and anything else that would be useful):

{
  "_links": {
    "pb:latest-pact-version": { "href: "..." }, //this is the one that the current clients use to display to the user using the "/latest" format
    "pb:pact-version": { "href: "..." }, //the permalink
    "pb:consumer-version": { "href: "..." },
    "pb:tags": [{ "href: "..." }]
  }
}

After publishing with this endpoint, the rest of the resources would look the same as they do using the current approach.

Another benefit of this new format is that we could easily add support for publishing different types of contracts, and by exchanging "consumerXXX" for "providerXXX" we can easily support provider published contracts the same way.

Technical background on why this is useful right now in the context of the new branches/environments support:

• Supporting the branch property for the version requires clients to add another call to the pact publishing code
• I had initially modelled a version (which most closely represents a git version IRL) as has having one branch. It was recently highlighted to me that this is not the case, and a git version can have multiple branches.
• Depending on how I modelled the one version -> many branches relationship, this would either require the client to make extra calls to the API to create a "branch" resource as it does now with with the tags, or to fetch the version resource, modify it by adding in the new branch to a branches array, then PUT/PATCH the updated resource back. This is putting a lot of application knowledge into the client that I don't want it to have. Having a flat contract publish endpoint allows me to hide the logic about how to handle the version->branch relationship from the clients.
• Having already written the client code for the current modelling of 1 version -> 1 branch, it really would have been just as easy to modify the code to use this new endpoint.

Future benefits

• Having one HTTP call instead of multiple will make it possible to to detect certain events that we can't currently detect (eg. a branch has been merged)
• This will allow us to publish non-pact contracts, and non JSON contracts (supporting the Pactflow roadmap)

[bethesque]

@uglyog thoughts?

[uglyog]

Only happy thoughts

[bethesque]

PR opened here #420