API Hub for Design Integration

Notice

PRE-REQUISITES

To use this feature, you will need:

For more information on integration and setup instructions, visit the API Hub for Design documentation.

Introduction

API Hub for Design supports integration with API Hub for Contract Testing. This enables API designers to avoid releasing breaking changes by using API Hub for Contract Testing to get visibility into their APIs and how they are consumed, all from within the API Hub for Design Editor.

launch-promo.gif

Setting up the integration

SwaggerHub integration scopes to an individual API in API Hub for Design. You will need to configure the integration for each API that you would like to check with API Hub for Contract Testing.

To setup the integration and run compatibility checks you will need the following:

  • A read-write API token associated with a User or System Account assigned the SwaggerHub role or equivalent permissions.API Tokens

  • A provider contract published to API Hub for Contract Testing.

To prevent breaking changes to your consumers, you will need one or more consumer contracts published to API Hub for Contract Testing also, however this is not mandatory to setup the integration.

To setup the integration, navigate to your API in API Hub for Design and click the "API Hub for Contract Testing" button. This will take you to the setup screen if you haven't already configured your account.

Note

If the button does not appear, you are not on an eligible plan.

After entering your API Hub for Contract Testing Base URL and Token, you can select the pacticipant (provider application) that maps to the API in API Hub for Design.

swaggerhub-setup.png

For full setup instructions, visit the API Hub for Design documentation.

Checking Compatibility

Running the compatibility check

The compatibility check can be invoked by pressing the "API Hub for Contract Testing" button and choosing "Check Compatibility".

Note

To be able to see this button and run the checks, you need to be an organization's owner, the Designer that created the API, or a Collaborator with editor access.

swaggerhub-check.png

If the check has been run previously and the current API has not been modified, the last check result will be shown.

Note

Unlike the can-i-deploy command in the bi-directional contract testing flow, this check does not ensure that provider self-verification results have been provided to get a passing status check. It simply checks if the selected consumer contracts are compatible with the given provider contract.

If you need this behaviour, the can-i-deploy check will ensure that the provider has confirmed it adheres to its provider contract.

Compatible result

If there are no incompatibilities, you will see the following screen:

swaggerhub-compatible.png

To see which consumers you are compatible with, choose "View Compatibility Check Result":

swaggerhub-compatiblity-check.png

Incompatible result

If one or more consumers are incompatible with the changes, you will see the following screen:

swaggerhub-incompatible.png

Click "View Compatibility Check Result" to expand the error information to diagnose and remediate any issues.

swaggerhub-incompatiblity-check.png

Contracts covered by the check

Consumer contracts must use the branches and releases feature - it is not compatible with the use of tags.

The compatibility check uses the following selection criteria:

  • The latest version for each consumer's main branch

  • Any consumer version deployed or released to an environment

In selector terminology, this would be:

  • { "mainBranch": true }

  • { "deployedOrReleased": true }

This means each application (participant) should explicitly set their main branch (for example, main, developer or master) and publish contracts for that branch, as well as using the record-deployment command.

See the documentation on selectors for additional information on how this work.

Interpreting failures

The following is a sample error response from the check.

  • Line 4 tells you the extent of the compatibility failures

  • Lines 6 and 21 are sub-headings for sub-sections that show the errors for a given selector

  • Within these sub-sections, the errors are then organised by Route, and then consumer.

    • In this example you can see the Route for GET /product/{id} is incompatible with the product-catalog-ui version consumer that is in development (line 11) and the version that has been deployed to Production (Line 26).

    • The error details include a message, the location in the API that the error relates to (if known), the location in the consumer contract, and the example value in the consumer contract.

The document hierarchy is:

  • Selector scope (for example, applications currently in development, or applications deployed to a particular environment)

  • Resource impacted, in the form OPERATION path (for example, GET /product/{id})

  • Consumer impacted (for example, product-catalog-ui)

  • Error

Compatibility Check
-------------------

This API is incompatible with some consumer contracts

Consumer applications currently in development
==============================================

### Incompatible routes

1. GET /product/{id}

* Incompatible with product-catalog-ui

Error message: Response body is incompatible with the response body schema in the spec file: should NOT have additional properties - id
API location: [root].paths./product/{id}.get.responses.200.content.application/json.schema.additionalProperties
Consumer contract value: {"id":"10","type":"CREDIT_CARD","name":"28 Degrees"}
Consumer contract location: [root].interactions[0].response.body


Consumer applications in Production Environment
===============================================

### Incompatible routes

1. GET /product/{id}

* Incompatible with product-catalog-ui

Error message: Response body is incompatible with the response body schema in the spec file: should NOT have additional properties - id
API location: [root].paths./product/{id}.get.responses.200.content.application/json.schema.additionalProperties
Consumer contract value: {"id":"10","type":"CREDIT_CARD","name":"28 Degrees"}
Consumer contract location: [root].interactions[0].response.body

See compatibility checks in the Bi-Directional Contract Testing section for more on these errors.

Integrating API Hub for Design into your CI/CD pipelines

The SwaggerHub integration supports the API Hub for Design Editor. To setup automation into your CI/CD workflows, follow this guide.

Troubleshooting

401 error when invoking the integration

{"code":400,"message":"Failed execute PactFlow check. Failed with error code: 401"}

The user associated with the API token has been disabled or expired.

403 error when invoking the integration

You receive the following error when running the compatibility check:

{"code":400,"message":"Failed execute PactFlow check. Failed with error code: 403"}

Your API token is read-only or missing relevant permissions (see #setting-up-the-integration).

Demo

Watch a short video demonstrating how integration works:

In this section:
© 2024
Publication date: