Swiftpack.co - Package - soto-project/soto

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.


Swift SDK for AWS that works on Linux, macOS and iOS

Soto for AWS

Swift 5.1 sswg:sandbox|94x20

Soto is a Swift language SDK for Amazon Web Services (AWS), working on Linux, macOS and iOS. This library provides access to all AWS services. The service APIs it provides are a direct mapping of the REST APIs Amazon publishes for each of its services. Soto is a community supported project and is in no way affiliated with AWS.

Table of Contents


The library consists of three parts

  1. soto-core which does all the core request encoding and signing, response decoding and error handling.
  2. The service api files which define the individual AWS services and their commands with their input and output structures.
  3. The CodeGenerator which builds the service api files from the JSON model files supplied by Amazon.

Swift Package Manager

Soto uses the Swift Package Manager to manage its code dependencies. To use Soto in your codebase it is recommended you do the same. Add a dependency to the package in your own Package.swift dependencies.

    dependencies: [
        .package(url: "https://github.com/soto-project/soto.git", from: "5.0.0")

Then add target dependencies for each of the Soto targets you want to use.

    targets: [
        .target(name: "MyApp", dependencies: [
            .product(name: "SotoS3", package: "soto"),
            .product(name: "SotoSES", package: "soto"),
            .product(name: "SotoIAM", package: "soto")

Alternatively if you are using Xcode 11 or later you can use the Swift Package Manager integration and add a dependency to Soto through that.


Soto works on Linux, macOS and iOS. It requires v2.0 of Swift NIO. If you use v1.0 of Swift NIO then you will need to use v3.5 of Soto. Below is a compatibility table for different Soto versions.

Version Swift MacOS iOS Linux Vapor
5.x 5.1 - 12.0 - Ubuntu 14.04-20.04 4.0
4.x 5.0 - 12.0 - Ubuntu 14.04-20.04 4.0
3.x 4.2 - Ubuntu 14.04-18.04 3.0

Configuring Credentials

Before using the SDK, you will need AWS credentials to sign all your requests. Credentials can be provided to the library in the following ways.

  • Environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY
  • ECS container IAM policy
  • EC2 IAM instance profile
  • Shared credentials file in your home directory
  • Static credentials provided at runtime

You can find out more about credential providers here

Using Soto

To use Soto you need to create an AWSClient and a service object for the AWS service you want to work with. The AWSClient provides all the communication with AWS and the service object provides the configuration and APIs for communicating with a specific AWS service. More can be found out about AWSClient here and the AWS service objects here.

Each Soto command returns a Swift NIO EventLoopFuture. An EventLoopFuture is not the response of the command, but rather a container object that will be populated with the response at a later point. In this manner calls to AWS do not block the main thread. It is recommended you familiarise yourself with the Swift NIO documentation, specifically EventLoopFuture if you want to take full advantage of Soto.

The recommended manner to interact with EventLoopFutures is chaining. The following function returns an EventLoopFuture that creates an S3 bucket, puts a file in the bucket, reads the file back from the bucket and finally prints the contents of the file. Each of these operations are chained together. The output of one being the input of the next.

import SotoS3 //ensure this module is specified as a dependency in your package.swift

let bucket = "my-bucket"

let client = AWSClient(
    credentialProvider: .static(accessKeyId: "Your-Access-Key", secretAccessKey: "Your-Secret-Key"),
    httpClientProvider: .createNew
let s3 = S3(client: client, region: .uswest2)

func createBucketPutGetObject() -> EventLoopFuture<S3.GetObjectOutput> {
    // Create Bucket, Put an Object, Get the Object
    let createBucketRequest = S3.CreateBucketRequest(bucket: bucket)

        .flatMap { response -> EventLoopFuture<S3.PutObjectOutput> in
            // Upload text file to the s3
            let bodyData = "hello world".data(using: .utf8)!
            let putObjectRequest = S3.PutObjectRequest(
                acl: .publicRead,
                body: bodyData,
                bucket: bucket,
                key: "hello.txt"
            return s3.putObject(putObjectRequest)
        .flatMap { response -> EventLoopFuture<S3.GetObjectOutput> in
            let getObjectRequest = S3.GetObjectRequest(bucket: bucket, key: "hello.txt")
            return s3.getObject(getObjectRequest)
        .whenSuccess { response in
            if let body = response.body {
                print(String(data: body, encoding: .utf8)!)


API Reference

Visit soto.codes to browse the user guides and api reference. As there is a one-to-one correspondence with AWS REST api calls and the Soto api calls, you can also use the official AWS documentation for more detailed information about AWS commands.

User guides

Additional user guides for specific elements of Soto are available


We welcome and encourage contributions from all developers. Please read CONTRIBUTING.md for our contributing guidelines.


Soto is released under the Apache License, Version 2.0. See LICENSE for details.


Support development of Soto by becoming a backer


Stars: 544
Last commit: 4 days ago



v5.1.0 - 2021-01-04T16:45:27

Using v5.1.0 of soto-core. Sync'ed service models to v1.36.19 of aws-sdk-go.

New Services

  • Audit Manager: helps you continuously audit your AWS usage.
  • EMR containers: Amazon EMR on EKS.
  • Greengrass v2: Version 2 of AWS IoT Greengrass, an open source Internet of Things (IoT) edge runtime and cloud service.
  • HealthLake: HIPAA-eligible service that stores, transforms, queries, and analyzes health data at petabyte scale.
  • IoT Device Advisor: Cloud-based, fully managed test capability for validating IoT devices during device software development.
  • IoT Fleet Hub: A new, easy way to monitor and interact with IoT device fleets.
  • IoT Wireless:
  • Location Service: Add location data to applications without sacrificing data security and user privacy.
  • Prometheus Service: Amazon Managed Service for Prometheus.
  • Sagemaker Edge Manager: Dataplane service for communicating with active agents.
  • Well Architected: Provides programmatic access to the AWS Well-Architected Tool in the AWS Management Console.

Minor Changes

  • Allow DateCoder property wrappers to be applied to shape member variables serialized into headers and queries. PR #455
  • Set the default format for dates stored in headers to be rfc822. PR #455
  • CognitoIdentity: Add IdentityProvider protocol to be used alongside cognitoIdentity credential provider. PR #453
  • S3: Add support for S3 dualstack and accelerated transfer endpoints. PR #457
  • STS: Add credential provider .stsWebIdentityTokenFile to support credential acquisition on EKS clusters.