REL03-BP03 API ごとにサービス契約を提供する - AWS Well-Architected Framework
実装のガイダンス実装手順リソース

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

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

期待される成果:

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

  • 厳密に型指定されたスキーマを使用しないサービス API を作成します。その結果、API バインディングの生成に使用できない API や、プログラムで検証できないペイロードが生成されます。

  • API の利用者に更新とリリースを強いるようなバージョニング戦略を採用していない。そうしないと、サービス契約が発展したときに失敗する。

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

  • サービスコンポーネントを個別にテストできるようにするために、API 契約を使用せずにテストケースを開発したりモック API 実装を使用したりします。

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

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

実装のガイダンス

ビジネスドメインを特定し、ワークロードのセグメント化を決定したら、サービス API を開発できます。まず、機械が読み取れる API のサービス契約を定義し、次に API バージョニング戦略を実装します。REST、GraphQL、非同期イベントなどの一般的なプロトコルでサービスを統合する準備ができたら、AWSのサービスをアーキテクチャに組み込んで、コンポーネントを厳密に型指定された API 契約と統合できます。

サービス API 契約の AWS のサービス

以下を含む AWS のサービスを Amazon API Gateway、AWS AppSync、 Amazon EventBridge アプリケーションで API サービス契約を使用するようにアーキテクチャに組み込むことができます。Amazon API Gateway は、ネイティブ AWS サービスや他の Web サービスと直接統合するのに役立ちます。API Gateway は、 OpenAPI 仕様 とバージョニングをサポートしています。AWS AppSync は、クエリ、ミューテーション、およびサブスクリプションのサービスインターフェイスを定義する GraphQL スキーマを定義することによって構成するマネージド GraphQL エンドポイントですAmazon EventBridge はイベントスキーマを使用してイベントを定義し、イベントのコードバインディングを生成します。

実装手順

  • まず、API の契約を定義します。契約では、API の機能を説明するだけでなく、API の入出力用に厳密に型指定されたデータオブジェクトとフィールドを定義します。

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

  • GraphQL API は次の方法で AWS AppSync を使用して定義および管理できます。 GraphQL スキーマファイルを定義して 契約インターフェイスを生成し、複雑な REST モデル、複数のデータベーステーブル、またはレガシーサービスとのやり取りを簡素化します。

  • AWS Amplify は、AWS AppSync と統合されたプロジェクトで、アプリケーションで使用するための厳密に型指定された JavaScript クエリファイルと、AWS AppSync GraphQL クライアントライブラリを Amazon DynamoDB テーブル用に生成します。

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

  • API の拡張またはバージョニング。オプションフィールドまたは必須フィールドのデフォルト値で構成できるフィールドを追加する場合、API を拡張する方が簡単なオプションです。

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

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

  • API をバージョニングするときは、ロジックを単一のコードベースで管理できるように、ファサードを使用してバージョンをサポートするプロキシバージョニングの実装を検討してください。

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

リソース

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

関連するドキュメント:

関連サンプル:

関連動画:

関連ツール: