AWS 서비스 API 모델 레포지터리 및 Maven 패키지 정식 공개

오늘, Amazon Web Services(AWS)를 위한 새로운 공개 API 모델 소스를 발표합니다. 이제 Maven Central에 매일 AWS API 모델을 게시하고 GitHub의 새로운 리포지토리에 대한 오픈 소스 액세스를 제공하고 있습니다. 이 리포지토리에는 AWS 퍼블릭 인터페이스 정의와 동작을 정의하는 Smithy API 모델의 최종 최신 소스가 포함되어 있습니다.

이러한 Smithy 모델을 사용하여 AWS 서비스를 더 잘 이해하고, AWS에 연결하기 위한 사용자 지정 소프트웨어 개발 키트(SDK), 명령줄 인터페이스(CLI) 등의 개발자 도구나 AWS에서 애플리케이션 통합을 검증하기 위한 테스트 도구를 구축할 수 있습니다.

AWS는 2018년부터 Smithy 모델을 사용하여 SDK 클라이언트와 CLI 도구를 생성해 왔습니다. 모든 AWS 서비스는 프로토콜, 인증, 요청 및 응답 유형, 오류와 같은 작업 및 동작을 포함하여 API 계약을 철저히 문서화하기 위해 Smithy에서 모델링됩니다.

이 퍼블릭 리소스를 사용하면 다음과 같이 AWS 서비스와 직접 통합할 수 있는 자체 애플리케이션을 자신 있게 구축하고 테스트할 수 있습니다.

SDK 클라이언트 생성 – Smithy 도구 체인을 사용하여 공식 AWS SDK 지원과 클라이언트 코드 생성기 없이 언어 커뮤니티를 위한 자체 목적별 SDK를 구축하여 클라이언트 SDK 라이브러리를 생성할 수 있습니다.
API 구현 생성 – 언어별 프레임워크에 대한 서버 스텁은 물론, AI 에이전트에 대한 모델 컨텍스트 프로토콜(MCP) 서버 구성을 생성할 수 있습니다. 자체 API 표준을 준수하는지 확인하기 위한 검증 기능이 내장되어 있습니다.
자체 개발자 도구 구축 – AWS를 기반으로 모의 테스트 도구, IAM 정책 생성기, AWS에 연결하기 위한 상위 수준 추상화 등 자체 도구를 구축할 수 있습니다.
AWS API 동작 이해 – 아티팩트를 간결하고 쉽게 조사하여 SDK가 API 직접 호출을 해석하는 방식과 해당 직접 호출에서 예상되는 동작을 빠르게 검토하고 이해할 수 있습니다.

AWS API 모델에 대해 자세히 알아보기
api-models-aws 리포지토리에 액세스하여 GitHub에서 직접 AWS 서비스 모델을 찾아볼 수 있습니다. 이 리포지토리에는 모든 퍼블릭 AWS API 서비스에 대한 JSON AST 형식의 Smithy 모델이 포함되어 있습니다. 모든 Smithy 모델은 모양과 특성으로 구성됩니다. 모양은 유형의 인스턴스이고 특성은 클라이언트, 서버 또는 문서에 유용할 수 있는 모양에 더 많은 정보를 추가하는 데 사용됩니다.

AWS 모델 리포지토리에는 다음이 포함됩니다.

최상위 서비스 디렉터리는 서비스의 <sdk-id>를 사용하여 이름이 지정되며, 여기서 <sdk-id>는 소문자로 표기되고 공백이 하이픈으로 변환된 모델의 sdkId 값입니다.
각 서비스 디렉터리에는 서비스의 <version>당 하나의 디렉터리가 포함되며, 여기서 <version>은 서비스 모양의 버전 속성 값입니다.
service-version 디렉터리 내에 <sdk-id>-<version>.json이라는 모델 파일이 존재합니다.

예를 들어 Amazon EC2 서비스에서 RunInstances API를 정의하려는 경우 이 모델은 리소스와 작업을 함께 집계하는 API의 진입점인 service 유형을 사용합니다. 멤버가 참조하는 모양을 target이라고 합니다.

com.amazonaws.ec2#AmazonEC2": {
      "type": "service",
      "version": "2016-11-15",
      "operations": [
....
        {
          "target": "com.amazonaws.ec2#RunInstances"
        },
....
	  ]

operation 유형은 API 작업의 입력, 출력, 특성 및 가능한 오류를 나타냅니다. 작업 모양은 리소스 모양과 서비스 모양에 바인딩됩니다. 작업은 operation_statement를 사용하여 IDL에서 정의됩니다. 특성에서 문서, 예제 등의 자세한 API 정보를 확인할 수 있습니다.

"com.amazonaws.ec2#RunInstances": {
      "type": "operation",
      "input": {
        "target": "com.amazonaws.ec2#RunInstancesRequest"
      },
      "output": {
        "target": "com.amazonaws.ec2#Reservation"
      },
      "traits": {
        "smithy.api#documentation": "<p>Launches the specified number of instances using an AMI for which you have....",
        smithy.api#examples": [
          {
            "title": "To launch an instance",
            "documentation": "This example launches an instance using the specified AMI, instance type, security group, subnet, block device mapping, and tags.",
            "input": {
              "BlockDeviceMappings": [
                {
                  "DeviceName": "/dev/sdh",
                  "Ebs": {
                    "VolumeSize": 100
                  }
                }
              ],
              "ImageId": "ami-abc12345",
              "InstanceType": "t2.micro",
              "KeyName": "my-key-pair",
              "MaxCount": 1,
              "MinCount": 1,
              "SecurityGroupIds": [
                "sg-1a2b3c4d"
              ],
              "SubnetId": "subnet-6e7f829e",
              "TagSpecifications": [
                {
                  "ResourceType": "instance",
                  "Tags": [
                    {
                      "Key": "Purpose",
                      "Value": "test"
                    }
                  ]
                }
              ]
            },
            "output": {}
          }
        ]
      }
    },

AWS는 서비스 API를 모델링하고 AWS SDK와 AWS CLI의 일일 릴리스를 제공하기 위해 Smithy를 광범위하게 사용하고 있습니다. AWS API 모델은 AWS 서비스와 상호 작용하기 위한 서버 스텁을 구현하는 데 유용할 수 있습니다.

AWS API 모델을 사용하여 구축하는 방법
Smithy API 모델은 빌드 도구, 클라이언트 또는 서버 코드 생성기, IDE 지원, 구현 등의 빌딩 리소스를 제공합니다. 예를 들어, Smithy CLI를 사용하면 모델을 쉽게 구축하고, 임시 검증을 실행하고, 모델을 비교하여 차이점을 찾고, 모델을 쿼리하는 등의 작업을 수행할 수 있습니다. Smithy CLI를 사용하면 Java를 설정하거나 Smithy Gradle 플러그인을 사용하지 않고도 Smithy 작업을 쉽게 시작할 수 있습니다.

AWS API 모델과 Smithy 빌드 도구를 사용하여 자체 애플리케이션을 구축하는 방법의 두 가지 예를 보여드리고자 합니다.

최소 SDK 클라이언트 구축 – 이 샘플 프로젝트는 Smithy TypeScript를 사용하여 Amazon DynamoDB용 최소 AWS SDK 클라이언트 생성을 시작하기 위한 템플릿을 제공합니다. Smithy 모델에서 최소 SDK를 구축한 다음 예제 코드를 실행할 수 있습니다. 자세한 내용은 여기에서 예제 프로젝트를 참조하세요.
MCP 서버 구축 – 이 샘플 프로젝트는 Smithy CLI를 사용하여 MCP StdIO 서버를 실행하는 데 필요한 모든 종속성을 포함하는 fat jar를 생성하기 위한 템플릿을 제공합니다. Smithy API로 도구를 모델링하여 MCP 서버를 구축하는 MCPServerExample과 모든 Smithy 서비스에 대한 프록시 MCP 서버를 생성하는 ProxyMCPExample을 찾을 수 있습니다. 자세한 내용은 GitHub 리포지토리를 참조하세요.

정식 출시
이제 Maven Central에서 사용 가능한 AWS API 모델 리포지토리와 서비스 모델 패키지에 대한 오픈 소스 액세스를 제공하는 AWS API 모델에 매일 액세스할 수 있습니다. 선택한 maven 패키지를 사용하여 모델을 가져오고 종속성을 추가할 수 있습니다.

AWS에서 선호하는 API 모델링 언어에 대해 자세히 알아보려면 Smithy.io와 해당 코드 생성 안내서를 참조하세요. 각 AWS SDK에 대해 자세히 알아보려면 AWS에서의 구축을 위한 도구와 SDK별 지원을 위한 해당 리포지토리를 방문하거나 평소 이용하는 AWS Support 담당자에게 문의하세요.

– Channy

Amazon Web Services 한국 블로그

AWS 서비스 API 모델 레포지터리 및 Maven 패키지 정식 공개

주요 링크 모음

팔로우하기