Erin Sparling
d8aa38be78
This PR adds an APIGateway V1 example, which differs slightly from the existing [V2 example](https://github.com/swift-server/swift-aws-lambda-runtime/tree/main/Examples/APIGateway). ### Motivation: While APIGatewayV2 has existed for a while, there are still some scenarios where V1 is preferable (see [Choose between REST APIs and HTTP APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html) for more details). This PR adds a working example for the `Api` endpoint type. ### Modifications: Sources/main.swift - Swapped APIGatewayRequestV2 and APIGatewayResponseV2 for their unversioned counterparts (aka V1). template.yaml - Changed the Events name and corresponding `Type: Api` values. - Added necessary additional properties to define a `GET` endpoint for an `Api` endpoint. Readme.md - Updated the request and response example outputs. ### Result: Now, an APIGateway and APIGatewayV1 example exist. > [!NOTE] > It is the author's opinion that this new example should technically be called `APIGateway` and the existing one should be renamed to `APIGatewayV2` to keep consistent with the request and response type naming conventions, but this is omitted from this request to be less disruptive.
This directory contains example code for Lambda functions.
Pre-requisites
-
Ensure you have the Swift 6.x toolchain installed. You can install Swift toolchains from Swift.org
-
When developing on macOS, be sure you use macOS 15 (Sequoia) or a more recent macOS version.
-
To build and archive your Lambda functions, you need to install docker.
-
To deploy your Lambda functions and invoke them, you must have an AWS account and install and configure the
awscommand line. -
Some examples are using AWS SAM. Install the SAM CLI before deploying these examples.
-
Some examples are using the AWS CDK. Install the CDK CLI before deploying these examples.
Examples
-
API Gateway: an HTTPS REST API with Amazon API Gateway and a Lambda function as backend (requires AWS SAM).
-
API Gateway with Lambda Authorizer: an HTTPS REST API with Amazon API Gateway protected by a Lambda authorizer (requires AWS SAM).
-
BackgroundTasks: a Lambda function that continues to run background tasks after having sent the response (requires AWS CLI).
-
CDK: a simple example of an AWS Lambda function invoked through an Amazon API Gateway and deployed with the Cloud Development Kit (CDK).
-
HelloJSON: a Lambda function that accepts JSON as an input parameter and responds with a JSON output (requires AWS CLI).
-
HelloWorld: a simple Lambda function (requires AWS CLI).
-
Hummingbird: a Lambda function using the Hummingbird web framework with API Gateway integration (requires AWS SAM).
-
S3EventNotifier: a Lambda function that receives object-upload notifications from an Amazon S3 bucket.
-
S3_AWSSDK: a Lambda function that uses the AWS SDK for Swift to invoke an Amazon S3 API (requires AWS SAM).
-
S3_Soto: a Lambda function that uses Soto to invoke an Amazon S3 API (requires AWS SAM).
-
Streaming: create a Lambda function exposed as an URL. The Lambda function streams its response over time. (requires AWS SAM).
-
Streaming+Codable: a Lambda function that combines JSON input decoding with response streaming capabilities, demonstrating a streaming codable interface (requires AWS SAM or the AWS CLI).
-
Testing: a test suite for Lambda functions.
AWS Credentials and Signature
This section is a short tutorial on the AWS Signature protocol and the AWS credentials.
What is AWS SigV4?
AWS SigV4, short for "Signature Version 4," is a protocol AWS uses to authenticate and secure requests. When you, as a developer, send a request to an AWS service, AWS SigV4 makes sure the request is verified and hasn’t been tampered with. This is done through a digital signature, which is created by combining your request details with your secret AWS credentials. This signature tells AWS that the request is genuine and is coming from a user who has the right permissions.
How to Obtain AWS Access Keys and Session Tokens
To start making authenticated requests with AWS SigV4, you’ll need three main pieces of information:
-
Access Key ID: This is a unique identifier for your AWS account, IAM (Identity and Access Management) user, or federated user.
-
Secret Access Key: This is a secret code that only you and AWS know. It works together with your access key ID to sign requests.
-
Session Token (Optional): If you're using temporary security credentials, AWS will also provide a session token. This is usually required if you're using temporary access (e.g., through AWS STS, which provides short-lived, temporary credentials, or for federated users).
To obtain these keys, you need an AWS account:
-
Sign up or Log in to AWS Console: Go to the AWS Management Console, log in, or create an AWS account if you don’t have one.
-
Create IAM User: In the console, go to IAM (Identity and Access Management) and create a new user. Ensure you set permissions that match what the user will need for your application (e.g., permissions to access specific AWS services, such as AWS Lambda).
-
Generate Access Key and Secret Access Key: In the IAM user credentials section, find the option to generate an "Access Key" and "Secret Access Key." Save these securely! You’ll need them to authenticate your requests.
-
(Optional) Generate Temporary Security Credentials: If you’re using temporary credentials (which are more secure for short-term access), use AWS Security Token Service (STS). You can call the
GetSessionTokenorAssumeRoleAPI to generate temporary credentials, including a session token.
With these in hand, you can use AWS SigV4 to securely sign your requests and interact with AWS services from your Swift app.