Introducing Amazon Web Services API models and publicly available resources for Amazon Web Services API definitions

Today, we’re announcing a new publicly available source of API models for Amazon Web Services (Amazon Web Services). We are now publishing Amazon Web Services API models on a daily basis to Maven Central and providing open source access to a new repository on GitHub. This repository includes a definitive, up-to-date source of Smithy API models that define Amazon Web Services public interface definitions and behaviors.

These Smithy models can be used to better understand Amazon Web Services services and build developer tools like custom SDKs and command line interfaces (CLIs) for connecting to Amazon Web Services or testing tools for validating your application integrations on Amazon Web Services.

Since 2018, we have been generating SDK clients and CLI tools using Smithy models. All Amazon Web Services services are modeled in Smithy to thoroughly document the API contract including operations and behaviors like protocols, authentication, request and response types, and errors.

With this public resource, you can build and test your own applications that can integrate directly with Amazon Web Services services with confidence such as:

• Generate SDK clients – You can build your own, purpose-built SDKs for language communities without official Amazon Web Services SDK support and client code generator using Smithy toolchain to generate client SDK libraries.
• Generating API implementations – You can generate server stubs for language-specific framework, even model context protocol (MCP) server configurations for your AI agents. You have built-in validation to ensure you adhere to your own API standards.
• Build your own developer tools – You can build your own tools on top of Amazon Web Services such as mock testing tools, IAM policy generators, or higher-level abstractions for connecting to Amazon Web Services.
• Understand Amazon Web Services API behaviors – You can concisely and easily investigate your artifact to quickly review and understand how SDKs interpret API calls and the behaviors to expect with those calls.

Learn about Amazon Web Services API models
You can browse the Amazon Web Services service models directly on GitHub by accessing the api-models-aws repository. This repository contains Smithy models with the JSON AST format for all public Amazon Web Services API services. All Smithy models consist of shapes and traits. Shapes are instances of types and traits are used to add more information to shapes that might be useful for clients, servers, or documentation.

The Amazon Web Services models repository contains:

• Top-level service directories are named using the <sdk-id> of the service, where <sdk-id> is the value of the model’s sdkId, lowercased and with spaces converted to hyphens
• Each service directory contains one directory per <version> of the service, where <version> is the value of the service shape’s version property.
• Contained within a service-version directory, a model file named <sdk-id>-<version>.json will be present

For example, when you want to define a RunInstances API in Amazon EC2 service, the model uses service type, an entry point of an API that aggregates resources and operations together. The shape referenced by a member is called its target.

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

The operation type represents the input, output, traits, and possible errors of an API operation. Operation shapes are bound to resource shapes and service shapes. An operation is defined in the IDL using an operation_statement. In the traits, you can find detailed API information such as documentation, examples, and so on.

"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": {}
          }
        ]
      }
    },

We use Smithy extensively to model our service APIs and provide the daily releases of the Amazon Web Services SDKs and Amazon Web Services CLI. Amazon Web Services API models can be helpful for implementing server stubs to interact with Amazon Web Services services.

How to build with Amazon Web Services API models
Smithy API models provide building resources such as build tools, client or server code generators, IDE support, and implementations. For example, with Smithy CLI, you can easily build your models, run ad-hoc validation, compare models for differences, query models, and more. The Smithy CLI makes it easy to get started working with Smithy without setting up Java or using the Smithy Gradle Plugins.

I want to show two examples how to build your own applications with Amazon Web Services API models and Smithy build tools.

• Build a minimal SDK client – This sample project provides a template to get started using Smithy TypeScript to create a minimal Amazon Web Services SDK client for Amazon DynamoDB. You can build the minimal SDK from the Smithy model, and then run the example code. To learn more, visit the example project here.
• Build MCP servers – This sample project provides a template to generate a fat jar which contains all the dependencies required to run an MCP StdIO server using the Smithy CLI. You can find MCPServerExample to build an MCP server by modeling tools as Smithy APIs and ProxyMCPExample to create a proxy MCP Server for any Smithy service. To learn more, visit the GitHub repository.

Now available
You can now access Amazon Web Services API models on a daily basis providing open-source access on the Amazon Web Services API models repository and service model packages available on Maven Central. You can import models and add dependencies using the maven package of your choice.

To learn more about the Amazon Web Services preferred API modeling language, visit Smithy.io and its code generation guide. To learn more each Amazon Web Services SDKs, visit Tools to Build on Amazon Web Services and its respective repository for SDK specific support or through your usual Amazon Support contacts.

— Channy

Channy Yun (윤석찬)

Channy is a Principal Developer Advocate for Amazon Web Services cloud. As an open web enthusiast and blogger at heart, he loves community-driven learning and sharing of technology.