# 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 ](https://aws.amazon.com/api-gateway/)、 [AWS AppSync](https://aws.amazon.com/appsync/)和 [Amazon EventBridge](https://aws.amazon.com/eventbridge/) 等 AWS 服務整合到您的架構中，以在應用程式中使用API服務合約。Amazon API Gateway 可協助您與直接原生 AWS 服務和其他 Web 服務整合。API Gateway 支援 [OpenAPI 規格](https://github.com/OAI/OpenAPI-Specification)和 versioning。 AWS AppSync 是您透過定義 [GraphQL](https://graphql.org/) 結構描述來定義查詢、突變和訂閱的服務界面所設定的受管 GraphQL 端點。Amazon EventBridge 使用事件結構描述來定義事件，並為您的事件產生程式碼繫結。
## 實作步驟
+ 首先，為您的 定義合約API。合約會表達 的功能API，並定義API輸入和輸出的強烈輸入資料物件和欄位。
+ 當您APIs在 API Gateway 中設定 時，您可以匯入和匯出端點的開放API規格。
+ [匯入 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測試工具的整合，並為服務消費者提供整合規格。
+ 您可以使用 APIs AWS AppSync 定義 GraphQL [結構描述檔案來定義和管理 GraphQL](https://docs.aws.amazon.com/appsync/latest/devguide/designing-your-schema.html)，以產生合約界面，並簡化與複雜REST模型、多個資料庫資料表或舊版服務的互動。
+ [AWS Amplify](https://aws.amazon.com/amplify/) 與 整合的專案 AWS AppSync 會產生強式 JavaScript 查詢檔案，用於您的應用程式，以及 [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) 資料表的 AWS AppSync GraphQL 用戶端程式庫。
+ 當您從 Amazon 取用服務事件時 EventBridge，事件會遵守已存在於結構描述登錄檔中的結構描述，或是您使用 OpenAPI Spec 定義的結構描述。使用登錄中定義的結構描述時，您也可以從結構描述合約產生用戶端繫結，以將程式碼與事件整合。
+ 擴展或版本您的 API。新增可使用選用欄位或必要欄位的預設值設定的欄位時，延伸 API 是更簡單的選項。
+ JSON REST和 GraphQL 等通訊協定的 型合約非常適合合約延伸。
+ XML 等通訊協定的 型合約SOAP應與 服務消費者進行測試，以判斷合約延伸的可行性。
+ 版本控制 時API，請考慮實作 Proxy 版本控制，其中使用外觀來支援版本，以便在單一程式碼庫中維護邏輯。
+ 使用 API Gateway，您可以使用[請求和回應映射](https://docs.aws.amazon.com/apigateway/latest/developerguide/request-response-data-mappings.html#transforming-request-response-body)，透過建立外觀來提供新欄位的預設值，或從請求或回應中刪除的欄位，以簡化吸收合約變更。透過此方法，基礎服務可以維護單一程式碼基底。
## 資源
**相關的最佳實務：**
+ [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/)
+ [ 在 上實作 Microservices AWS](https://docs.aws.amazon.com/whitepapers/latest/microservices-on-aws/microservices-on-aws.html)
+ [微型服務權衡](https://martinfowler.com/articles/microservice-trade-offs.html)
+ [微型服務 - 此新架構術語的定義](https://www.martinfowler.com/articles/microservices.html)
+ [ 上的微服務 AWS](https://aws.amazon.com/microservices/)
+ [ 使用 API Gateway 擴充功能開啟API ](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html)
+ [ 開啟 API-規格 ](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：設定RESTAPI使用開啟API ](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-import-api.html)
+ [ 使用 Open 的 Amazon API Gateway 至 Amazon DynamoDB CRUD 應用程式API ](https://serverlessland.com/patterns/apigw-ddb-openapi-crud?ref=search)
+ [ 無伺服器時代的現代應用程式整合模式：APIGateway Service Integration ](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 實作標頭型API閘道版本控制 CloudFront ](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)
**相關影片：**
+ [ 使用在 中開啟API AWS SAM 管理API閘道 ](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/)