{{!--
This is the README Handlebars template for `aws-sdk-rust`.
It gets instantiated and copied into the build artifacts by the `aws:sdk:assemble` build target.

Available template arguments:
- `{{sdk_version_<crate_name_in_snake_case>}}` (e.g., `{{sdk_version_aws_config}}` for the `aws-config` crate): the version number of the given crate (just the number, no `v` prefix)
- `{{msrv}}`: The MSRV Rust compiler version (just the number, no `v` prefix)
--}}
<!--
IMPORTANT:
This README file is auto-generated by the build system in smithy-lang/smithy-rs.
To update it, edit the `aws/SDK_README.md.hb` Handlebars template in that repository.
-->

# The AWS SDK for Rust [![Docs](https://img.shields.io/badge/docs-blue)](https://awslabs.github.io/aws-sdk-rust/) ![MSRV](https://img.shields.io/badge/msrv-{{msrv}}-red) [![Usage Guide](https://img.shields.io/badge/Developer_Guide-blue)](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/welcome.html)

This repo contains the AWS SDK for Rust and its [public roadmap](https://github.com/orgs/awslabs/projects/50/views/1).

The SDK is code generated from [Smithy models](https://smithy.io/2.0/index.html) that represent each AWS service.
The code used to generate the SDK can be found in [smithy-rs](https://github.com/smithy-lang/smithy-rs).

## Getting Started with the SDK

> Examples are available for many services and operations, check out the [examples folder](./examples).

> For a step-by-step guide including several advanced use cases, check out the [Developer Guide](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/welcome.html).

The SDK provides one crate per AWS service. You must add [Tokio](https://crates.io/crates/tokio) as a dependency within your Rust project to execute asynchronous code.

1. Create a new Rust project: `cargo new sdk-example`
2. Add dependencies to DynamoDB and Tokio to your **Cargo.toml** file:

    ```toml
    [dependencies]
    aws-config = { version= "{{sdk_version_aws_config}}", features = ["behavior-version-latest"] }
    aws-sdk-dynamodb = "{{sdk_version_aws_sdk_dynamodb}}"
    tokio = { version = "1", features = ["full"] }
    ```

3. Provide your AWS credentials with the default credential provider chain, which currently looks in:
   - Environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION`
   - The default credentials files located in `~/.aws/config` and `~/.aws/credentials` (location can vary per platform)
   - Web Identity Token credentials from the environment or container (including EKS)
   - ECS Container Credentials (IAM roles for tasks)
   - EC2 Instance Metadata Service (IAM Roles attached to instance)

4. Make a request using DynamoDB

```rust
use aws_sdk_dynamodb::{Client, Error};

#[tokio::main]
async fn main() -> Result<(), Error> {
    let shared_config = aws_config::load_from_env().await;
    let client = Client::new(&shared_config);
    let req = client.list_tables().limit(10);
    let resp = req.send().await?;
    println!("Current DynamoDB tables: {:?}", resp.table_names);
    Ok(())
}
```

### Prerequisites

In order to use the SDK, you must already have Rust and Cargo installed. If you don't, [these instructions](https://doc.rust-lang.org/book/ch01-01-installation.html) describe how to install Rust and Cargo.

## Using the SDK

Detailed usage instructions are available in the [Developer Guide](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/welcome.html).
Suggestions for additional sections or improvements for the guide are welcome. Please open an issue describing what you are trying to do.

## Getting Help
* [Developer Guide](https://docs.aws.amazon.com/sdk-for-rust/latest/dg/welcome.html)
* [GitHub discussions](https://github.com/awslabs/aws-sdk-rust/discussions) - For ideas, RFCs & general questions
* [GitHub issues](https://github.com/awslabs/aws-sdk-rust/issues/new/choose) – For bug reports & feature requests
* [Generated Docs (latest version)](https://awslabs.github.io/aws-sdk-rust/)
* [Usage examples](./examples)

## Feedback and Contributing

### Feedback

The SDK uses **GitHub Issues** to track feature requests and issues with the SDK. In addition, we use **GitHub Projects** to provide users with a high level view of our roadmap and the features we're actively working on.

You can provide feedback or report a bug  by submitting a **GitHub issue**.
This is the preferred mechanism to give feedback so that other users can engage in the conversation, +1 issues, etc.
Issues you open will be evaluated for our roadmap.

### Contributing

If you are interested in contributing to the SDK, please take a look at [CONTRIBUTING](CONTRIBUTING.md)

## Supported Rust Versions (MSRV)

The SDK currently requires a minimum of Rust {{msrv}}, and is not guaranteed to build on compiler versions
earlier than that. We keep the minimum compiler version two releases behind the latest stable release where
possible (so if the latest stable were 1.55, we would support 1.53). Increases in minimum required Rust
version will be called out in the Release Notes for new releases of the SDK.

## Additional Resources

- Design docs - Design documentation for the SDK lives in the [design folder of smithy-rs](https://github.com/smithy-lang/smithy-rs/tree/main/design).
- Runtime / Handwritten code: The Rust Runtime code that underpins the SDK can be accessed [here](https://github.com/smithy-lang/smithy-rs/tree/main/rust-runtime) and [here](https://github.com/smithy-lang/smithy-rs/tree/main/aws/rust-runtime). This code is copied into this repo as part of code generation.
- [Code Examples](./examples)
- [API reference documentation (rustdoc)](https://awslabs.github.io/aws-sdk-rust/)

## Security

See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.

## License

This project is licensed under the Apache-2.0 License.
