<section class="blog-post-content lb-rtxt"><table id="amazon-polly-audio-table"><tbody><tr><td id="amazon-polly-audio-tab"><p></p></td></tr></tbody></table><p>Today, we’re announcing a new publicly available source of API models for <a href="https://aws.amazon.com/">Amazon Web Services (AWS)</a>. We are now publishing AWS API models on a daily basis to <a href="https://central.sonatype.com/search?namespace=software.amazon.api.models&amp;sort=name">Maven Central</a> and providing open source access to a new repository on <a href="https://github.com/aws/api-models-aws">GitHub</a>. This repository includes a definitive, up-to-date source of <a href="https://smithy.io/">Smithy API models</a> that define AWS public interface definitions and behaviors.</p><p>These Smithy models can be used to better understand AWS services and build developer tools like custom software development kits (SDK) and command line interfaces (CLIs) for connecting to AWS or testing tools for validating your application integrations on AWS.</p><p>Since 2018, we have been generating SDK clients and CLI tools using <a href="https://aws.amazon.com/blogs/developer/tag/smithy/">Smithy models</a>. All AWS services are modeled in Smithy to thoroughly document the API contract including operations and behaviors like protocols, authentication, request and response types, and errors.</p><p>With this public resource, you can build and test your own applications that can integrate directly with AWS services with confidence such as:</p><ul><li><strong>Generate SDK clients</strong> – You can build your own, purpose-built SDKs for language communities without <a href="https://docs.aws.amazon.com/sdkref/latest/guide/version-support-matrix.html">official AWS SDK support</a> and client code generator using Smithy toolchain to <a href="https://smithy.io/2.0/tutorials/full-stack-tutorial.html#generating-the-client">generate client SDK libraries</a>.</li><li><strong>Generating API implementations</strong> – You can generate server stubs for language-specific framework, even <a href="https://modelcontextprotocol.io/introduction">model context protocol (MCP)</a> server configurations for your AI agents. You have built-in validation to ensure you adhere to your own API standards.</li><li><strong>Build your own developer tools</strong> – You can build your own tools on top of AWS such as mock testing tools, IAM policy generators, or higher-level abstractions for connecting to AWS.</li><li><strong>Understand AWS API behaviors</strong> – 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.</li></ul><p><strong class="c4">Learn about AWS API models</strong><br />You can browse the AWS service models directly on GitHub by accessing the <code>api-models-aws</code> repository. This repository contains Smithy models with the <a href="https://smithy.io/2.0/spec/json-ast.html">JSON AST</a> format for all public AWS API services. All Smithy models consist of shapes and traits. <a href="https://smithy.io/2.0/spec/model.html#shapes">Shapes</a> are instances of <code>types</code> and <a href="https://smithy.io/2.0/spec/model.html#traits">traits</a> are used to add more information to shapes that might be useful for clients, servers, or documentation.</p><p>The AWS models repository contains:</p><ul><li>Top-level service directories are named using the <code><sdk-id></code> of the service, where <code><sdk-id></code> is the value of the model’s <a href="https://smithy.io/2.0/aws/aws-core.html#sdkid">sdkId</a>, lowercased and with spaces converted to hyphens</li><li>Each service directory contains one directory per <code><version></code> of the service, where <code><version></code> is the value of the service shape’s <a href="https://smithy.io/2.0/spec/service-types.html#service">version property</a>.</li><li>Contained within a service-version directory, a model file named <<code>sdk-id>-<version>.json</code> will be present</li></ul><p>For example, when you want to define a <code>RunInstances</code> API in <a href="https://aws.amazon.com/ec2">Amazon EC2</a> service, the model uses <code>service</code> type, an entry point of an API that aggregates resources and operations together. The shape referenced by a member is called its <code>target</code>.</p><pre class="lang-json">com.amazonaws.ec2#AmazonEC2": { "type": "service", "version": "2016-11-15", "operations": [.... { "target": "com.amazonaws.ec2#RunInstances" },.... ]</pre><p>The <code>operation</code> type represents the input, output, traits, and possible errors of an API operation. Operation shapes are bound to <a href="https://smithy.io/2.0/spec/service-types.html#resource">resource</a> shapes and <a href="https://smithy.io/2.0/spec/service-types.html#service">service</a> shapes. An operation is defined in the IDL using an <a href="https://smithy.io/2.0/spec/idl.html#idl-operation">operation_statement</a>. In the traits, you can find detailed API information such as documentation, examples, and so on.</p><pre class="lang-json">"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": {} } ] } },</pre><p>We use Smithy extensively to model our service APIs and provide the daily releases of the <a href="https://aws.amazon.com/developer/tools/">AWS SDKs</a> and <a href="https://aws.amazon.com/cli/">AWS CLI</a>. AWS API models can be helpful for implementing server stubs to interact with AWS services.</p><p><strong class="c4">How to build with AWS API models<br /></strong> Smithy API models provide <a href="https://github.com/smithy-lang/awesome-smithy">building resources</a> such as build tools, client or server code generators, IDE support, and implementations. For example, with <a href="https://smithy.io/2.0/guides/smithy-cli/index.html">Smithy CLI</a>, 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 <a class="reference internal" href="https://smithy.io/2.0/guides/gradle-plugin/index.html#smithy-gradle-plugin">Smithy Gradle Plugins</a>.</p><p>I want to show two examples how to build your own applications with AWS API models and Smithy build tools.</p><ul><li><strong>Build a minimal SDK client</strong> – This sample project provides a template to get started using <a href="https://github.com/smithy-lang/smithy-typescript/">Smithy TypeScript</a> to create a minimal AWS 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 <a href="https://github.com/smithy-lang/smithy-examples/tree/main/smithy-typescript-examples/minimal-aws-sdk-client">example project</a> here.</li><li><strong>Build MCP servers</strong> – This sample project provides a template to generate a fat jar which contains all the dependencies required to run a MCP <code>StdIO</code> server using the Smithy CLI. You can find <code>MCPServerExample</code> to build an MCP server by modeling tools as Smithy APIs and <code>ProxyMCPExample</code> to create a proxy MCP Server for any Smithy service. To learn more, visit the <a href="https://github.com/smithy-lang/smithy-java/tree/main/examples/mcp-server">GitHub repository</a>.</li></ul><p><strong class="c4">Now available<br /></strong> You can now access AWS API models on a daily basis providing open-source access on the <a href="https://github.com/aws/api-models-aws">AWS API models repository</a> and service model packages available on <a href="https://central.sonatype.com/search?namespace=software.amazon.api.models&amp;sort=name">Maven Central</a>. You can import models and add dependencies using the maven package of their choice.</p><p>To learn more about the AWS preferred API modeling language, visit <a href="https://smithy.io/">Smithy.io</a> and its <a href="https://smithy.io/2.0/guides/using-code-generation/index.html">code generation guide</a>. To learn more each AWS SDKs, visit <a href="https://aws.amazon.com/developer/tools/">Tools to Build on AWS</a> and its <a href="https://github.com/aws">respective repository</a> for SDK specific support or through your usual AWS Support contacts.</p><p>— <a href="https://twitter.com/channyun">Channy</a></p></section><aside id="Comments" class="blog-comments"><div data-lb-comp="aws-blog:cosmic-comments" data-env="prod" data-content-id="1b5d2b17-ec45-4682-84c9-b749f3131b0f" data-title="Introducing AWS API models and publicly available resources for AWS API definitions" data-url="https://aws.amazon.com/blogs/aws/introducing-aws-api-models-and-publicly-available-resources-for-aws-api-definitions/"><p data-failed-message="Comments cannot be loaded… Please refresh and try again.">Loading comments…</p></div></aside>
