REL03-BP03 ごとにサービス契約を提供する API - 信頼性の柱
実装のガイダンス実装手順リソース

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

REL03-BP03 ごとにサービス契約を提供する API

サービス契約は、マシン読み取り可能なAPI定義で定義されたAPIプロデューサーとコンシューマー間の文書化された契約です。契約バージョニング戦略により、コンシューマーは既存の の使用を継続APIし、準備APIができたら新しいアプリケーションに移行できます。プロデューサーのデプロイは、契約がある限りいつでも行うことができます。サービスチームは、選択したテクノロジースタックを使用してAPI契約を満たすことができます。

望ましい結果： サービス指向アーキテクチャまたはマイクロサービスアーキテクチャで構築されたアプリケーションは、ランタイム依存関係を統合しながら独立して動作できます。API コンシューマーまたはプロデューサーにデプロイされた変更は、双方が共通のAPI契約に従っていても、システム全体の安定性を妨げません。サービスを介して通信するコンポーネントAPIsは、独立した機能リリース、ランタイム依存関係へのアップグレード、またはディザスタリカバリ (DR) サイトへのフェイルオーバーを実行することができ、相互にほとんどまたはまったく影響しません。さらに、ディスクリートサービスでは、他のサービスを一斉にスケールインしなくても、吸収するリソース需要を個別にスケールできます。

一般的なアンチパターン:

  • 強く型付けされたスキーマAPIsを使用しないサービスの作成。これにより、プログラムで検証APIsできないAPIバインディングやペイロードの生成に を使用することはできません。

  • バージョニング戦略を採用していないため、サービス契約が進化したときにAPIコンシューマーが更新、リリース、または失敗することを余儀なくされます。

  • ドメインコンテキストや言語での統合の失敗を説明するのではなく、基盤となるサービス実装の詳細を漏らすエラーメッセージ。

  • サービスコンポーネントの独立したテストを可能にするテストケースとモックAPI実装の開発にAPI契約を使用しない。

このベストプラクティスを確立する利点： APIサービス契約を介して通信するコンポーネントで構成される分散システムは、信頼性を向上させることができます。デベロッパーは、コンパイル中にタイプチェックを行い、開発プロセスの早い段階で潜在的な問題を検出して、リクエストとレスポンスがAPI契約に従っており、必須フィールドが存在することを確認できます。API 契約は、 APIs とプロバイダーの明確な自己ドキュメント化インターフェイスを提供し、さまざまなシステムとプログラミング言語間の相互運用性を向上させます。

このベストプラクティスを活用しない場合のリスクレベル: 中

実装のガイダンス

ビジネスドメインを特定し、ワークロードセグメンテーションを決定したら、サービス を開発できますAPIs。まず、 のマシン読み取り可能なサービス契約を定義しAPIs、APIバージョニング戦略を実装します。REST、GraphQL 、または非同期イベントなどの一般的なプロトコルでサービスを統合できる準備ができたら、アーキテクチャに AWS サービスを組み込むことで、コンポーネントを強力なタイプのAPI契約と統合できます。

AWS サービスAPI競合のサービス

Amazon API Gateway 、、Amazon EventBridge などの AWS サービスをアーキテクチャに組み込みAWS AppSync、アプリケーションでAPIサービス契約を使用します。Amazon API Gateway は、直接ネイティブ AWS サービスやその他のウェブサービスとの統合に役立ちます。API Gateway は Open API仕様とバージョニングをサポートしています。 AWS AppSync は、クエリ、ミューテーション、サブスクリプションのサービスインターフェイスを定義する GraphQL スキーマを定義して設定するマネージド GraphQL エンドポイントです。Amazon EventBridge はイベントスキーマを使用してイベントを定義し、イベントのコードバインディングを生成します。

実装手順

  • まず、 の契約を定義しますAPI。契約では、 の機能を表現APIし、API入力と出力の強力な型付けされたデータオブジェクトとフィールドを定義します。

  • API Gateway APIsで を設定すると、エンドポイントの OpenAPI Specifications をインポートおよびエクスポートできます。

  • GraphQL スキーマファイルを定義 AWS AppSync して APIsGraphQL を定義および管理することで、契約インターフェイスを生成し、複雑なRESTモデル、複数のデータベーステーブル、またはレガシーサービスとのインタラクションを簡素化できます。 GraphQL

  • AWS Amplify と統合されている プロジェクトは、アプリケーションで使用する強力なタイプの JavaScript クエリファイルと、Amazon DynamoDB テーブル用の AWS AppSync GraphQL クライアントライブラリ AWS AppSync を生成します。

  • Amazon からサービスイベントを使用する場合 EventBridge、イベントはスキーマレジストリに既に存在するスキーマ、または OpenAPI Spec で定義したスキーマに従います。レジストリでスキーマを定義すると、スキーマ契約からクライアントバインディングを生成して、コードをイベントと統合することもできます。

  • を拡張またはバージョン管理しますAPI。拡張APIは、オプションのフィールドまたは必須フィールドのデフォルト値で設定できるフィールドを追加する場合の簡単なオプションです。

    • JSON RESTや GraphQL などのプロトコルの ベースの契約は、契約延長に適しています。

    • XML のようなプロトコルのベース契約は、サービスコンシューマーとテストして、契約延長の実現可能性を判断するSOAP必要があります。

  • をバージョニングする場合はAPI、ファサードを使用してバージョンをサポートするプロキシバージョニングの実装を検討し、ロジックを単一のコードベースで維持できるようにします。

    • API Gateway では、リクエストとレスポンスのマッピングを使用して、新しいフィールドのデフォルト値を提供するファサードを確立したり、リクエストやレスポンスから削除されたフィールドを削除したりすることで、契約変更の吸収を簡素化できます。このアプローチにより、基盤となるサービスが単一のコードベースを維持できます。

リソース

関連するベストプラクティス:

関連ドキュメント:

関連する例:

関連動画:

関連ツール: