# REL03-BP03 API ごとにサービス契約を提供する
<a name="rel_service_architecture_api_contracts"></a>

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

 **期待される成果:** 

 **一般的なアンチパターン:** サービス指向またはマイクロサービスアーキテクチャで構築されたアプリケーションは、ランタイム依存関係を統合しながら独立して動作できます。API コンシューマーまたはプロデューサーに変更をデプロイしても、双方が共通の API 契約に従っていれば、システム全体の安定性が損なわれることはありません。サービス API を介して通信するコンポーネントは、相互にほとんどまたはまったく影響を与えずに、独立した機能リリース、ランタイム依存関係のアップグレード、またはディザスタリカバリ (DR) サイトへのフェイルオーバーを実行できます。さらに、ディスクリートサービスでは、他のサービスを一斉にスケーリングしなくても、吸収するリソース需要を個別にスケーリングできます。 
+  厳密に型指定されたスキーマを使用しないサービス API を作成します。その結果、API バインディングの生成に使用できない API や、プログラムで検証できないペイロードが生成されます。 
+  API の利用者に更新とリリースを強いるようなバージョニング戦略を採用していない。そうしないと、サービス契約が発展したときに失敗する。 
+  ドメインコンテキストや言語での統合の失敗を説明するのではなく、基盤となるサービス実装の詳細を漏らすエラーメッセージ。 
+  サービスコンポーネントを個別にテストできるようにするために、API 契約を使用せずにテストケースを開発したりモック API 実装を使用したりします。 

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

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

## 実装のガイダンス
<a name="implementation-guidance"></a>

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

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

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

## 実装手順
<a name="implementation-steps"></a>
+  まず、API の契約を定義します。契約では、API の機能を説明するだけでなく、API の入出力用に厳密に型指定されたデータオブジェクトとフィールドを定義します。 
+  API Gateway で API を設定すると、エンドポイントの OpenAPI 仕様をインポートおよびエクスポートできます。 
  +  [OpenAPI 定義をインポートする](https://docs.aws.amazon.com/apigateway/latest/developerguide/import-edge-optimized-api.html) API の作成が簡単になり、次のようなコードツールとして AWS インフラストラクチャと統合できます [AWS Serverless Application Model](https://aws.amazon.com/serverless/sam/) および [AWS Cloud Development Kit (AWS CDK)](https://aws.amazon.com/cdk/). 
  +  [API 定義をエクスポートすると、](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-export-api.html) API テストツールとの統合が簡素化され、サービス利用者に統合仕様が提供されます。 
+  GraphQL API は次の方法で AWS AppSync を使用して定義および管理できます。 [GraphQL スキーマファイルを定義して](https://docs.aws.amazon.com/appsync/latest/devguide/designing-your-schema.html) 契約インターフェイスを生成し、複雑な REST モデル、複数のデータベーステーブル、またはレガシーサービスとのやり取りを簡素化します。 
+  [AWS Amplify](https://aws.amazon.com/amplify/) は、AWS AppSync と統合されたプロジェクトで、アプリケーションで使用するための厳密に型指定された JavaScript クエリファイルと、AWS AppSync GraphQL クライアントライブラリを [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) テーブル用に生成します。 
+  Amazon EventBridge からサービスイベントを利用する場合、イベントはスキーマレジストリに既に存在するスキーマや OpenAPI 仕様で定義したスキーマに従います。レジストリでスキーマを定義すると、スキーマ契約からクライアントバインディングを生成して、コードをイベントと統合することもできます。 
+  API の拡張またはバージョニング。オプションフィールドまたは必須フィールドのデフォルト値で構成できるフィールドを追加する場合、API を拡張する方が簡単なオプションです。 
  +  REST や GraphQL などのプロトコルの JSON ベースの契約は、契約の拡張に適しています。 
  +  SOAP のようなプロトコルの XML ベースの契約をサービスコンシューマーとテストして、契約延長の可能性を判断する必要があります。 
+  API をバージョニングするときは、ロジックを単一のコードベースで管理できるように、ファサードを使用してバージョンをサポートするプロキシバージョニングの実装を検討してください。 
  +  API Gatewayを使用すると、 [リクエストとレスポンスのマッピングを使用して、](https://docs.aws.amazon.com/apigateway/latest/developerguide/request-response-data-mappings.html#transforming-request-response-body) 新しいフィールドにデフォルト値を提供したり、リクエストまたはレスポンスから削除されたフィールドを削除するファサードを確立したりすることで、契約の変更の吸収を簡素化できます。この方法では、基盤となるサービスは単一のコードベースを維持できます。 

## リソース
<a name="resources"></a>

 **関連するベストプラクティス:** 
+  [REL03-BP01 ワークロードをセグメント化する方法を選択する](rel_service_architecture_monolith_soa_microservice.md) 
+  [REL03-BP02 特定のビジネスドメインと機能に重点を置いたサービスを構築する](rel_service_architecture_business_domains.md) 
+  [REL04-BP02 疎結合の依存関係を実装する](rel_prevent_interaction_failure_loosely_coupled_system.md) 
+  [REL05-BP03 再試行呼び出しを制御および制限する](rel_mitigate_interaction_failure_limit_retries.md) 
+  [REL05-BP05 クライアントタイムアウトを設定する](rel_mitigate_interaction_failure_client_timeouts.md) 

 **関連するドキュメント:** 
+ [ API (アプリケーションプログラミングインターフェイス) とは。 ](https://aws.amazon.com/what-is/api/)
+ [AWS でのマイクロサービスの実装 ](https://docs.aws.amazon.com/whitepapers/latest/microservices-on-aws/microservices-on-aws.html)
+ [ マイクロサービスのトレードオフ ](https://martinfowler.com/articles/microservice-trade-offs.html)
+ [ Microservices - a definition of this new architectural term ](https://www.martinfowler.com/articles/microservices.html)
+ [AWS でのマイクロサービス ](https://aws.amazon.com/microservices/)
+ [ OpenAPI の API Gateway 拡張機能の使用 ](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html)
+ [ OpenAPI 仕様 ](https://github.com/OAI/OpenAPI-Specification)
+ [ GraphQL: スキーマとタイプ ](https:/graphql.org/learn/schema)
+ [ Amazon EventBridge コードバインディング ](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-schema-code-bindings.html)

 **関連サンプル:** 
+ [ Amazon API Gateway: OpenAPI を使用した REST API の設定 ](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html)
+ [ OpenAPI を使用した Amazon API Gateway から Amazon DynamoDB への CRUD アプリケーション ](https://serverlessland.com/patterns/apigw-ddb-openapi-crud?ref=search)
+ [ サーバーレス時代のモダンアプリケーション統合パターン: API Gateway サービス統合 ](https://catalog.us-east-1.prod.workshops.aws/workshops/be7e1ee7-b91f-493d-93b0-8f7c5b002479/en-US/labs/asynchronous-request-response-poll/api-gateway-service-integration)
+ [ Amazon CloudFront を使用したヘッダーベースの API Gateway バージョニングの実装 ](https://aws.amazon.com/blogs/compute/implementing-header-based-api-gateway-versioning-with-amazon-cloudfront/)
+ [AWS AppSync: クライアントアプリケーションの構築 ](https://docs.aws.amazon.com/appsync/latest/devguide/building-a-client-app.html#aws-appsync-building-a-client-app)

 **関連動画:** 
+ [AWS SAM で OpenAPI を使用して API Gateway を管理する ](https://www.youtube.com/watch?v=fet3bh0QA80)

 **関連ツール:** 
+ [ Amazon API Gateway ](https://aws.amazon.com/api-gateway/)
+ [AWS AppSync](https://aws.amazon.com/appsync/)
+ [ Amazon EventBridge ](https://aws.amazon.com/eventbridge/)