|
1 | | -# AWS SDK for Swift |
2 | | - |
3 | | -The **AWS SDK for Swift** is a pure Swift SDK for accessing any & all AWS services. |
4 | | - |
5 | | -## License |
6 | | - |
7 | | -This library is licensed under the Apache 2.0 License. |
| 1 | +# <img alt="aws_logo.png" src="https://avatars.githubusercontent.com/u/3299148?s=200&v=4" width="28"> AWS SDK for Swift |
8 | 2 |
|
9 | 3 | [![License][apache-badge]][apache-url] |
10 | 4 |
|
11 | 5 | [apache-badge]: https://img.shields.io/badge/License-Apache%202.0-blue.svg |
12 | 6 | [apache-url]: LICENSE |
13 | 7 |
|
14 | | -## Requirements |
| 8 | +## Getting Started |
| 9 | + |
| 10 | +- [SDK Product Page](https://aws.amazon.com/sdk-for-swift/) |
| 11 | +- [Developer Guide](https://docs.aws.amazon.com/sdk-for-swift/latest/developer-guide/home.html) |
| 12 | +- [API Reference](https://sdk.amazonaws.com/swift/api/awssdkforswift/latest/documentation/awssdkforswift) |
| 13 | +- [Code Examples Repo](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift) |
| 14 | + |
| 15 | +To get started using the SDK, follow the setup instructions at [Set up the AWS SDK for Swift](https://docs.aws.amazon.com/sdk-for-swift/latest/developer-guide/setting-up.html), then check out our step-by-step tutorial at [Get started with the AWS SDK for Swift](https://docs.aws.amazon.com/sdk-for-swift/latest/developer-guide/getting-started.html). |
| 16 | + |
| 17 | +## Feedback |
15 | 18 |
|
16 | | -The AWS SDK for Swift supports the following: |
17 | | -- Swift 5.9 or higher |
18 | | -- iOS & iPadOS 13.0 or higher |
19 | | -- macOS 10.15 or higher |
20 | | -- Ubuntu Linux 16.04 LTS or higher |
21 | | -- Amazon Linux 2 or higher |
| 19 | +If you'd like to provide feedback, report a bug, request a feature, or would like to bring |
| 20 | +attention to an issue in general, please do so by submitting a GitHub issue to the repo [here](https://github.com/awslabs/aws-sdk-swift/issues/new/choose). |
22 | 21 |
|
23 | | -Other environments (watchOS, tvOS, Windows, or others) may work but have not been verified. |
| 22 | +This is the preferred mechanism for user feedback as it allows anyone with similar issue or suggestion to engage in conversation as well. |
24 | 23 |
|
25 | | -These supported versions may change in the future. |
| 24 | +## Contributing |
26 | 25 |
|
27 | | -## Provide Credentials |
| 26 | +If you are interested in contributing to AWS SDK for Swift, see [CONTRIBUTING](CONTRIBUTING.md) for more information. |
| 27 | + |
| 28 | +## Development |
| 29 | + |
| 30 | +### Runtime Modules (under `Sources/Core/`) |
| 31 | + |
| 32 | +* `AWSClientRuntime` - concrete types, protocols, enums, etc. that provide most AWS specific runtime functionalities for the SDK. |
| 33 | + Has several other runtime modules as its dependencies. |
| 34 | +* `AWSSDKChecksums` - implementation for handling checksum in AWS requests |
| 35 | +* `AWSSDKCommon` - concrete types used by other runtime modules |
| 36 | +* `AWSSDKEventStreamsAuth` - concrete types for signing AWS event stream message |
| 37 | +* `AWSSDKHTTPAuth` - concrete types for AWS SigV4 signer, and types related to auth flow |
| 38 | +* `AWSSDKIdentity` - concrete types for AWS credentials and identity resolvers |
| 39 | + |
| 40 | +> 📖 For more information on runtime modules, see [the AWS Runtime Module Documentation in API reference](https://sdk.amazonaws.com/swift/api/awssdkforswift/latest/documentation/awssdkforswift#AWS-Runtime-Module-Documentation) |
| 41 | +
|
| 42 | +## License |
28 | 43 |
|
29 | | -For virtually all AWS operations, you must provide AWS security credentials for the SDK to use. |
| 44 | +This library is licensed under the Apache 2.0 License. |
30 | 45 |
|
31 | | -You can accomplish this for local development by installing and configuring the |
32 | | -[AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) |
33 | | -on your development machine. The AWS SDK for Swift will share the AWS CLI's credentials (written at |
34 | | -`~/.aws/credentials`) when executing on your development machine. |
| 46 | +## Security |
35 | 47 |
|
36 | | -See your AWS account administrator to obtain your credentials if you do not already have them. |
37 | | - |
38 | | -## Test the AWS SDK for Swift with your credentials |
39 | | - |
40 | | -Here, we'll be creating a simple Swift package to show you how the SDK is used, and verify that the SDK can use your |
41 | | -credentials to access a live AWS service. |
42 | | - |
43 | | -You can perform this on either Mac or Linux on any supported OS version, but must have a supported version of either |
44 | | -Xcode (for Mac) or the Swift toolchain (for Linux) installed. |
45 | | - |
46 | | -Be sure you've set up AWS credentials on your development machine, per the section above. |
47 | | - |
48 | | -1. On your command line, create a new, executable Swift package: |
49 | | -``` |
50 | | -$ mkdir AWSCredentialTester |
51 | | -$ cd AWSCredentialTester |
52 | | -$ swift package init --type executable |
53 | | -``` |
54 | | - |
55 | | -2. Edit your new package's `Package.swift` file to read: |
56 | | -``` |
57 | | -// swift-tools-version: 5.9 |
58 | | -
|
59 | | -import PackageDescription |
60 | | -
|
61 | | -let package = Package( |
62 | | - name: "AWSCredentialTester", |
63 | | - platforms: [.macOS(.v10_15), .iOS(.v13)], |
64 | | - dependencies: [ |
65 | | - .package(url: "https://github.com/awslabs/aws-sdk-swift.git", from: "0.16.0") |
66 | | - ], |
67 | | - targets: [ |
68 | | - .executableTarget( |
69 | | - name: "AWSCredentialTester", |
70 | | - dependencies: [ |
71 | | - .product(name: "AWSSTS", package: "aws-sdk-swift") |
72 | | - ], |
73 | | - path: "Sources" |
74 | | - ) |
75 | | - ] |
76 | | -) |
77 | | -``` |
78 | | - |
79 | | -3. Edit your project's `Sources/main.swift` file to read: |
80 | | -``` |
81 | | -import AWSSTS |
82 | | -
|
83 | | -let client = try STSClient(region: "us-east-1") |
84 | | -let input = GetCallerIdentityInput() |
85 | | -let output = try await client.getCallerIdentity(input: input) |
86 | | -let userID = output.userId ?? "not known" |
87 | | -print("Caller's AWS user ID is \(userID)") |
88 | | -``` |
89 | | - |
90 | | -4. Execute your Swift package from the command line: |
91 | | -``` |
92 | | -$ swift run |
93 | | -``` |
94 | | -Your package will resolve dependencies, compile, and run. |
95 | | - |
96 | | -In the terminal output, you will see (after a number of log statements): |
97 | | -``` |
98 | | -Caller's AWS user ID is <an alphanumeric string> |
99 | | -``` |
100 | | -(this user ID should match your AWS Access Key ID for your AWS credentials.) |
101 | | - |
102 | | -If you’ve made it this far... congratulations! 🎉 |
103 | | - |
104 | | -## Integrating Into an Existing Xcode Project or Package |
105 | | - |
106 | | -Now that you've tested the SDK and your credentials in a simple project, here are steps to quickly get the AWS SDK for |
107 | | -Swift installed into either your existing Xcode project or Swift package. |
108 | | - |
109 | | -### Installing the AWS SDK for Swift into your Xcode Project |
110 | | - |
111 | | -1. Open your project in the Xcode IDE. From the drop down menu, select File > Add Packages... |
112 | | - |
113 | | -2. In the field labeled "Search or Enter Package URL", enter "https://github.com/awslabs/aws-sdk-swift". Set the |
114 | | -dependency rule and project as needed, then click "Add Package". The package will download and install to your Xcode |
115 | | -project. |
116 | | - |
117 | | -3. In the "Choose Package Products for aws-sdk-swift" popup window, check the box next to the specific AWS services you |
118 | | -want to access, and set the Xcode target next to each service. Click "Add Package". |
119 | | - |
120 | | -### Installing the AWS SDK for Swift into your Swift Package |
121 | | - |
122 | | -1. In your package's `Package.swift`, add AWS SDK for Swift as a package dependency: |
123 | | -``` |
124 | | -let package = Package( |
125 | | - name: "MyPackage", |
126 | | - dependencies: [ |
127 | | -+ .package(url: "https://github.com/awslabs/aws-sdk-swift", from: "0.16.0") |
128 | | - ], |
129 | | -``` |
130 | | - |
131 | | -2. Add the specific AWS services you plan to use into the `dependencies` of one of the targets in your package's |
132 | | -`Package.swift`. To finish this example, you will need to add at least `AWS Secure Token Service (STS)` : |
133 | | -``` |
134 | | - targets: [ |
135 | | - .target( |
136 | | - name: "MyTarget", |
137 | | - dependencies: [ |
138 | | -+ .product(name: "AWSS3", package: "aws-sdk-swift"), |
139 | | -+ .product(name: "AWSSTS", package: "aws-sdk-swift"), |
140 | | -+ .product(name: "AWSTranscribe", package: "aws-sdk-swift") |
141 | | - ] |
142 | | - ) |
143 | | - ] |
144 | | -``` |
145 | | -See the AWS SDK for Swift's [`Package.swift`](Package.swift) file for the names of all available AWS services. |
146 | | - |
147 | | -*What’s next?* |
148 | | -Try some other AWS services. Help us better understand what you think the most critical features are next. Give us |
149 | | -feedback on your experience. etc... |
150 | | - |
151 | | -*Run into a bug?* |
152 | | -Please file a Github issue on this project. We try to respond within a business day. |
153 | | - |
154 | | -## API Reference documentation |
155 | | -We recommend that you use the documentation generation capabilities within Xcode (Option+Click on a symbol); if you run |
156 | | -across an API that is not documented, please file an issue in this project. |
157 | | - |
158 | | -Generated online documentation will be provided soon. |
| 48 | +Please refer to our [security policy](https://github.com/awslabs/aws-sdk-swift/security/policy). |
0 commit comments