SmartBear

HTTP Methods

RESTful API operations are based on the HTTP Request Method standard as defined by RFC7231 and RFC5788.

PactFlow REST APIs adhere to this standard, where the meaning of the key operations is described below:

Method	Operation	Description
`GET`	Read	Retrieve a resource representation for the given URI. Data is only retrieved and never modified.
`POST`	Create	Create a sub-resource as part of a collection resource. This operation is not relevant for singular resources. In some cases, a `POST` request may be used as a query interface for advanced data fetching, similar to a GraphQL query.
`PUT`	Create/Update	Create a resource with the given URI or replace (full update) a resource when the resource already exists.
`PATCH`	Update	Partially updates an existing resource. The request only contains the resource modifications instead of the full resource representation. JSON Patch is used as the standard for representing changes.
`DELETE`	Delete	Remove a resource with a given URI.

HTTP Status Codes

Successful operations are reported with a status code in the 2xx series.
2xx series status codes are returned only if the complete execution is successful.
Failures are reported in the 4xx or 5xx series.
Failures return a problem details body as described by the Problem Details section (see Errors).

HATEOAS Links

[Hypermedia as the Engine of Application State (HATEOS) is a principle of the REST application architecture that makes it more resilient to changes of resource URLs over time.

Relations are the key mechanism to provide this resiliency and are present in all API responses via the _links property.

This excerpt from a sample response shows an array of HATEOAS links using the HAL format PactFlow uses:

{
  "_links": {
    "self": {
      "href": "https://foo.pactflow.io",
      "title": "Index",
      "templated": false
    },
    "pf:publish-provider-contract": {
      "href": "https://foo.pactflow.io/provider-contracts/provider/{provider}/publish",
      "title": "Publish provider contract",
      "templated": true
    },
    "pb:pacticipants": {
      "href": "https://foo.pactflow.io/pacticipants",
      "title": "Pacticipants",
      "templated": false
    }
    ...
}

Relations

The prefix on a relation indicates the type of resource it links to:

pb: - resources that inherit from the open-source Pact Broker.
pf: - PactFlow specific resources.
self - the current resource.
next - a link to the next resource, e.g. the next page in a collection.
previous - a link to the previous resource, e.g. the previous page in a collection.
others - all other prefixes should be avoided and are considered unsupported. For example, you may see the beta prefix, which is occasionally used to test out or experiment with a new API.

For general guidance on HAL, see the RFC.

NOTE: PactFlow may change the URL used in a relation as per the principles of API evolution supported by the HATEOS approach. To preserve backwards compatibility, however, all resources will continue to be available at their pre-existing URLs. Breaking URL changes will only be introduced with a major version release.

Best Practices

Set the Accept header to allow at both application/hal+json and application/problem+json. e.g. Accept: application/hal+json, application/problem+json.

When using our hypermedia API, it is recommended to follow links from the root resource (/) and navigate using the relations (e.g., pb:publish-provider-contract) to the target resource, rather than hard-coding URLs to specific resources.