コントラクト テスト ツール「API Hub for Contract Testing」を使ってみよう！パート 3: 互換性を損なう変更の例

この記事では、API Hub for Contract Testing を使って、コントラクト (契約) テストを開発ワークフローに統合して、デザイン ファーストの API 開発を実現する方法を全 3 パートのシリーズとして紹介します。

パート 1 ではプロバイダー (API 提供者) 側の操作について、パート 2 ではコンシューマー (API 利用者) 側の操作について説明しました。パート 3 となる本記事では、互換性を損なう API 変更の可能性について考えてみましょう。

パート 1 とパート 2 をまだお読みになっていない場合は、先にご覧になることを推奨します。

互換性を損なう API 変更には、主に次の 2 種類があります。

  1. コンシューマーが、存在しないプロバイダーに新しい期待値 (例: 新しいフィールド/エンドポイント) を追加する場合。
  2. プロバイダーが、既存のコンシューマーに影響を与える変更 (例: フィールドの削除または名前変更、エンドポイントの変更) を行う場合。

API Hub for Contract Testing は、can-i-deploy を使用してこのような状況を検出します。can-i-deploy は、コンシューマー コントラクトがターゲット環境におけるプロバイダー コントラクトの有効なサブセットであるかどうかをチェックします。

コンシューマーが必要とするフィールドの削除

API Hub for Design で行われる可能性のある 2 つの変更について考えてみましょう。1 つは、コンシューマーが必要とするフィールドの名前を変更するという安全でない操作です。

実際に試してみましょう。

API Hub for Design で以下の操作を行います。

  1. 前の手順で作成した API 定義を開きます。
  2. Product スキーマの name フィールドを firstName に変更します。
    swaggerhub-remove-name.png

  3. [Save] をクリックします。
  4. [Sync] をクリックします。
  5. コミット メッセージを feat: removing name field に変更します。
    sync-management.png

  6. [Push] をクリックします。
pact-publish-oas-actions.png
Run pactflow/actions/publish-provider-contract@v1.0.1
Successfully published provider contract for pactflow-example-provider version 1.0.0-3a694151f8837a8f38ed80124e9d81530d614dde-design to API Hub for Contract Testing

API Hub for Contract Testing の互換性を損なう変更の防止

can-i-deploy が失敗した場合について考えてみましょう。

can-i-deploy-failed.png
pact-broker can-i-deploy --pacticipant pactflow-example-provider --version="1.0.0-3a694151f8837a8f38ed80124e9d81530d614dde-design" --to-environment production

Computer says no ¯_(ツ)_/¯

CONSUMER                  | C.VERSION  | PROVIDER                  | P.VERSION               | SUCCESS? | RESULT#
--------------------------|------------|---------------------------|-------------------------|----------|--------
pactflow-example-consumer | 253c165... | pactflow-example-provider | 1.0.0-3a69415...-design | false    | 1      

VERIFICATION RESULTS
--------------------
1. https://saflow.pactflow.io/contracts/bi-directional/provider/pactflow-example-provider/version/1.0.0-3a694151f8837a8f38ed80124e9d81530d614dde-design/consumer/pactflow-example-consumer/version/253c165958d15624ce7245d5739689860439d24b/cross-contract-verification-results (failure)

The cross contract verification between the pact for the version of pactflow-example-consumer currently deployed or released to production (253c165958d15624ce7245d5739689860439d24b) and the oas for version 1.0.0-3a694151f8837a8f38ed80124e9d81530d614dde-design of pactflow-example-provider failed

API Hub for Contract Testing は、コンシューマーのニーズをフィールド レベルまですべて把握しているため、このビルドは失敗します。

API Hub for Contract Testing の UI にアクセスし、[contract comparison] タブまでドリルダウンすると、コンシューマーとプロバイダーのコントラクトを比較した出力が表示されます。この例では、コンシューマーが必要とするフィールドを、プロバイダーがサポートしていないことを警告しています。

失敗理由の解釈方法については、こちらを参照してください。

互換性を損なわない変更

互換性を損なわない変更について考えてみましょう。name フィールドを firstName に変更します。コンシューマー が firstName を使用するようにコードを変更するまで、name フィールドの使用をサポートするように、両方のプロパティを Product スキーマに追加します。

API Hub for Design で以下の操作を行います。

  1. 前の手順で作成した API 定義を開きます。
  2. Product スキーマに name フィールドを追加して、name と firstName の両方を含めます。
    swaggerhub-add-firstname.png

  3. [Save] をクリックします。
  4. [Sync] をクリックします。
  5. コミット メッセージを feat: adding firstName field に変更します。
    swaggerhub-add-firstname-push-change.png
  6. [Push] をクリックします。
provider-build-triggered.png
provider-contract-published.png
Run pactflow/actions/publish-provider-contract@v1.0.1
Successfully published provider contract for pactflow-example-provider version 1.0.0-4bff20fab7b711b66a508c999690547d9559d12b-design to API Hub for Contract Testing

互換性があると検証されたデザイン

can-i-deploy-passed.png
pact-broker can-i-deploy --pacticipant pactflow-example-provider --version="1.0.0-4bff20fab7b711b66a508c999690547d9559d12b-design" --to-environment production
Computer says yes \o/ 

CONSUMER                  | C.VERSION  | PROVIDER                  | P.VERSION               | SUCCESS? | RESULT#
--------------------------|------------|---------------------------|-------------------------|----------|--------
pactflow-example-consumer | 253c165... | pactflow-example-provider | 1.0.0-4bff20f...-design | true     | 1      

VERIFICATION RESULTS
--------------------
1. https://saflow.pactflow.io/contracts/bi-directional/provider/pactflow-example-provider/version/1.0.0-4bff20fab7b711b66a508c999690547d9559d12b-design/consumer/pactflow-example-consumer/version/253c165958d15624ce7245d5739689860439d24b/cross-contract-verification-results (success)

All required verification results are published and successful

API Hub for Contract Testing は、コンシューマーのニーズをフィールド レベルまですべて把握しているため、このビルドは成功します。コンシューマーのリクエストは Product スキーマのサブセットであるため、これは安全な操作です。

そして、コンシューマーのコードを更新して firstName を使用するようにし、name フィールドを廃止できるようにします。

github-workflow-overview.png

まとめ

  1. コンシューマーが使用していないフィールドは、プロバイダーから安全に削除できます。
  2. コンシューマーが使用しているフィールド/エンドポイントをプロバイダーから削除することは安全ではありません。API Hub for Contract Testing はこの状況を検出します。
  3. API Hub for Contract Testing は、プロバイダーがまだサポートしていない変更をコンシューマーがデプロイするのを防ぎます。

この記事では、API Hub for Design と API Hub for Contract Testing の双方向コントラクト テスト機能がどのように機能し、ソフトウェアを迅速かつ確実に本番環境にリリースできるかについて紹介しました。

以下のガイドも参考にしてください。

パート 3 では、互換性を損なう API 変更の例について説明しました。

全 3 パートで構成されるこのシリーズでは、API Hub for Contract Testing を使って、コントラクト (契約) テストを開発ワークフローに統合して、デザイン ファーストの API 開発を実現する方法を紹介しました。

この資料は、SmartBear の Web サイトで公開されている API Hub for Contract Testing University ドキュメントの「Design First With API Hub for Design」にある「Quick Start Guide with Github Actions」を参考に作成しました。

タイトルとURLをコピーしました