AWS Unveils API Models and Public Resources for API Definitions

Exploring the Latest Release of AWS API Models: A Gateway to Enhanced Development

In a notable development for developers and technology enthusiasts, Amazon Web Services (AWS) has announced a new and publicly accessible source of API models. This initiative enables AWS API models to be published daily on Maven Central, while also providing open-source access via a new repository on GitHub. This repository serves as a definitive, up-to-date resource for Smithy API models, which define AWS public interface definitions and behaviors.

AWS’s Smithy models are valuable tools for developers aiming to gain a deeper understanding of AWS services. They facilitate the creation of developer tools, such as custom software development kits (SDKs) and command-line interfaces (CLIs), which can connect to AWS. Additionally, these models can be used to create testing tools for validating application integrations with AWS.

Since 2018, AWS has been utilizing Smithy models to generate SDK clients and CLI tools. All AWS services are modeled using Smithy, which thoroughly documents the API contract, including operations and behaviors such as protocols, authentication, request and response types, and errors.

This public resource offers developers the opportunity to build and test their applications with confidence, integrating directly with AWS services. Here are some of the ways developers can utilize these models:

1. Generate SDK Clients: Developers can create their own, purpose-built SDKs for language communities that lack official AWS SDK support. By using the Smithy toolchain, they can generate client SDK libraries tailored to their specific needs.
2. Generate API Implementations: Developers can generate server stubs for language-specific frameworks, including model context protocol (MCP) server configurations for AI agents. This built-in validation ensures adherence to API standards.
3. Build Developer Tools: Developers can create tools on top of AWS, such as mock testing tools, IAM policy generators, or higher-level abstractions for connecting to AWS.
4. Understand AWS API Behaviors: Developers can investigate their artifacts to quickly review and understand how SDKs interpret API calls and the behaviors to expect from those calls.

   Understanding AWS API Models

   Developers can explore AWS service models directly on GitHub through the api-models-aws repository. This repository contains Smithy models in the JSON Abstract Syntax Tree (AST) format for all public AWS API services. Smithy models are composed of shapes and traits. Shapes represent instances of types, while traits add additional information to shapes that may be useful for clients, servers, or documentation.

   The AWS models repository includes:

   • Top-level service directories named using the service’s sdk-id, lowercased and with spaces converted to hyphens.
   • Each service directory contains a directory for each version of the service, corresponding to the service shape’s version property.
   • Within a service-version directory, a model file named using the format sdk-id-version.json is present.

     For instance, when defining the RunInstances API in the Amazon EC2 service, the model uses a service type as an entry point that aggregates resources and operations. The shape referenced by a member is referred to as its target.

     Building with AWS API Models

     Smithy API models provide numerous building resources, such as build tools, client or server code generators, integrated development environment (IDE) support, and implementations. The Smithy CLI allows developers to easily build models, run ad-hoc validation, compare models for differences, query models, and more. The Smithy CLI simplifies the process of working with Smithy without requiring Java setup or the Smithy Gradle Plugins.

     Here are two examples of how developers can build applications using AWS API models and Smithy build tools:

5. Build a Minimal SDK Client: This sample project provides a template for using Smithy TypeScript to create a minimal AWS SDK client for Amazon DynamoDB. Developers can build the minimal SDK from the Smithy model and run example code. More information can be found in the example project on GitHub.
6. Build MCP Servers: This sample project provides a template to generate a fat jar containing all dependencies required to run an MCP StdIO server using the Smithy CLI. Developers can use MCPServerExample to build an MCP server by modeling tools as Smithy APIs and ProxyMCPExample to create a proxy MCP Server for any Smithy service. More information is available in the GitHub repository.

   Availability and Further Learning

   AWS API models are now accessible on a daily basis, providing open-source access through the AWS API models repository. Service model packages are also available on Maven Central, allowing developers to import models and add dependencies using their preferred Maven packages.

   To learn more about Smithy, AWS’s preferred API modeling language, visit Smithy.io and its code generation guide. For more information about AWS SDKs, visit AWS’s Tools to Build on AWS page and the respective repository for SDK-specific support.

   This announcement by AWS represents a significant step forward in facilitating enhanced development and integration with AWS services. By providing developers with access to comprehensive API models, AWS continues to empower developers to build, test, and innovate with greater confidence and efficiency.

For more Information, Refer to this article.