REL03-BP03 에 따른 서비스 계약 제공 API - AWS Well-Architected 프레임워크
구현 지침구현 단계리소스

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

REL03-BP03 에 따른 서비스 계약 제공 API

서비스 계약은 기계가 읽을 수 있는 API 정의에 정의된 API 생산자와 소비자 간의 문서화된 계약입니다. 계약 버전 관리 전략을 통해 소비자는 기존 를 계속 사용하고 준비가 API 되면 애플리케이션을 최신 버전으로 API 마이그레이션할 수 있습니다. 생산자 배포는 계약을 준수하는 한 언제든지 가능합니다. 서비스 팀은 선택한 기술 스택을 사용하여 API 계약을 충족할 수 있습니다.

원하는 결과: 서비스 지향 또는 마이크로서비스 아키텍처로 구축된 애플리케이션은 통합 런타임 종속성을 유지하면서 독립적으로 작동할 수 있습니다. API 소비자 또는 생산자에게 배포된 변경 사항은 양 측이 공통 API 계약을 따를 때 전체 시스템의 안정성을 중단하지 않습니다. 서비스를 통해 통신하는 구성 요소는 독립적인 기능 릴리스, 런타임 종속성에 대한 업그레이드 또는 재해 복구(DR) 사이트로의 장애 조치를 수행할 APIs 수 있으며 서로 영향을 거의 또는 전혀 미치지 않습니다. 또한 개별 서비스는 다른 서비스를 함께 확장할 필요 없이 독립적으로 확장하여 리소스 수요를 흡수할 수 있습니다.

일반적인 안티 패턴:

  • 강력하게 입력된 스키마 APIs 없이 서비스를 생성합니다. 이로 인해 프로그래밍 방식으로 검증할 수 APIs 없는 API 바인딩 및 페이로드를 생성하는 데 를 사용할 수 없습니다.

  • 서비스 계약이 발전할 때 API 소비자가 업데이트 및 릴리스하거나 실패하도록 하는 버전 관리 전략을 채택하지 않습니다.

  • 도메인 컨텍스트 및 언어에서의 통합 실패를 설명하는 대신 기본 서비스 구현의 세부 정보를 유출하는 오류 메시지.

  • API 계약을 사용하여 서비스 구성 요소를 독립적으로 테스트할 수 있도록 테스트 사례 및 모의 API 구현을 개발하지 않습니다.

이 모범 사례 설정의 이점: API 서비스 계약을 통해 통신하는 구성 요소로 구성된 분산 시스템은 신뢰성을 개선할 수 있습니다. 개발자는 컴파일 중에 유형 확인을 통해 개발 프로세스 초기에 잠재적 문제를 포착하여 요청 및 응답이 API 계약을 따르고 필수 필드가 있는지 확인할 수 있습니다. API 계약은 APIs 및 공급자를 위한 명확한 자체 문서화 인터페이스를 제공하여 다양한 시스템과 프로그래밍 언어 간의 상호 운용성을 높입니다.

이 모범 사례가 확립되지 않을 경우 노출되는 위험 수준: 중간

구현 가이드

비즈니스 도메인을 식별하고 워크로드 세분화를 결정한 후에는 서비스를 개발할 수 있습니다APIs. 먼저 에 대한 기계 판독 가능 서비스 계약을 정의한 APIs다음 API 버전 관리 전략을 구현합니다. REST, GraphQL 또는 비동기 이벤트와 같은 일반적인 프로토콜을 통해 서비스를 통합할 준비가 되면 AWS 서비스를 아키텍처에 통합하여 구성 요소를 강력한 유형의 API 계약과 통합할 수 있습니다.

AWS 서비스 API 대비에 대한 서비스

Amazon API Gateway , AWS AppSync및 Amazon EventBridge을 포함한 AWS 서비스를 아키텍처에 통합하여 애플리케이션에서 API 서비스 계약을 사용합니다. Amazon API Gateway를 사용하면 직접 네이티브 AWS 서비스 및 기타 웹 서비스와 통합할 수 있습니다. API Gateway는 OpenAPI 사양 및 버전 관리를 지원합니다. AWS AppSync 는 쿼리, 돌연변이 및 구독에 대한 서비스 인터페이스를 정의하기 위해 GraphQL 스키마를 정의하여 구성하는 관리형 GraphQL 엔드포인트입니다. Amazon은 이벤트 스키마를 EventBridge 사용하여 이벤트를 정의하고 이벤트에 대한 코드 바인딩을 생성합니다.

구현 단계

  • 먼저 에 대한 계약을 정의합니다API. 계약은 의 기능을 표현할 뿐만 API 아니라 API 입력 및 출력에 대해 강력하게 입력된 데이터 객체와 필드를 정의합니다.

  • API GatewayAPIs에서 를 구성할 때 엔드포인트의 오픈API 사양을 가져오고 내보낼 수 있습니다.

  • GraphQL 스키마 파일을 정의하여 계약 인터페이스를 생성하고 복잡한 REST 모델, 여러 데이터베이스 테이블 또는 레거시 서비스와의 상호 작용을 간소화APIs AWS AppSync 하여 로 GraphQL을 정의하고 관리할 수 있습니다. GraphQL

  • AWS Amplify 와 통합된 프로젝트는 애플리케이션에서 사용할 수 있는 강력한 형식의 JavaScript 쿼리 파일과 Amazon DynamoDB 테이블용 AWS AppSync GraphQL 클라이언트 라이브러리를 AWS AppSync 생성합니다.

  • Amazon 에서 서비스 이벤트를 사용하는 경우 EventBridge이벤트는 스키마 레지스트리에 이미 있거나 OpenAPI Spec으로 정의한 스키마를 준수합니다. 레지스트리에 정의된 스키마를 사용하면 스키마 계약에서 클라이언트 바인딩을 생성하여 코드를 이벤트와 통합할 수도 있습니다.

  • 를 확장하거나 버전화합니다API. 를 확장하는 API 것은 선택적 필드 또는 필수 필드의 기본값으로 구성할 수 있는 필드를 추가할 때 더 간단한 옵션입니다.

    • JSON REST 및 GraphQL과 같은 프로토콜에 대한 기반 계약은 계약 연장에 적합할 수 있습니다.

    • XML 와 같은 프로토콜에 대한 기반 계약은 서비스 소비자와 테스트하여 계약 연장의 가능성을 결정SOAP해야 합니다.

  • 의 버전을 지정할 때는 단일 코드베이스에서 로직을 유지할 수 있도록 facade를 사용하여 버전을 지원하는 프록시 버전 관리를 구현하는 것이 API좋습니다.

    • API Gateway를 사용하면 요청 및 응답 매핑을 사용하여 새 필드에 기본값을 제공하거나 요청 또는 응답에서 제거된 필드를 제거하도록 정면을 설정하여 계약 변경 사항 흡수를 간소화할 수 있습니다. 이 접근 방식을 사용하면 기본 서비스가 단일 코드베이스를 유지할 수 있습니다.

리소스

관련 모범 사례:

관련 문서:

관련 예제:

관련 비디오:

관련 도구: