AWS SAM (Serverless Application Model)

The AWS Serverless Application Model (SAM) is an open-source framework for building serverless applications on AWS. It extends CloudFormation with simplified syntax for defining Lambda functions, API Gateway APIs, DynamoDB tables, and other serverless resources. SAM also includes a CLI for local development, testing, and deployment.

---

Why SAM?

Building serverless applications with raw CloudFormation is verbose. A single Lambda function with an API Gateway trigger requires dozens of lines of CloudFormation. SAM reduces this to a few lines:

CloudFormation (without SAM) — ~80 lines

# You need to define:
# - AWS::Lambda::Function
# - AWS::Lambda::Permission
# - AWS::ApiGateway::RestApi
# - AWS::ApiGateway::Resource
# - AWS::ApiGateway::Method
# - AWS::ApiGateway::Deployment
# - AWS::ApiGateway::Stage
# - AWS::IAM::Role
# - AWS::IAM::Policy
# ... plus wiring them all together

SAM — ~15 lines

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31

Resources:
  HelloFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs20.x
      Events:
        HelloApi:
          Type: Api
          Properties:
            Path: /hello
            Method: get

SAM's Transform: AWS::Serverless-2016-10-31 directive tells CloudFormation to expand SAM resources into full CloudFormation resources at deployment time.

---

SAM CLI

The SAM CLI is the command-line tool for building, testing, and deploying SAM applications:

# Install SAM CLI
brew install aws-sam-cli        # macOS
pip install aws-sam-cli         # Python

# Verify installation
sam --version

Key SAM CLI Commands

Command	Purpose
sam init	Create a new SAM project from a template
sam build	Build your application (install dependencies, compile)
sam local invoke	Invoke a function locally with a test event
sam local start-api	Start a local API Gateway for testing
sam local start-lambda	Start a local Lambda endpoint
sam validate	Validate your SAM template
sam deploy	Deploy your application to AWS
sam logs	Fetch and tail CloudWatch logs
sam delete	Delete your deployed application

---

Project Structure

A typical SAM project follows this structure:

graph TD
  root["my-serverless-app/"]
  root --> tpl["template.yaml — SAM template (infrastructure definition)"]
  root --> cfg["samconfig.toml — Deployment configuration"]
  root --> src["src/"]
  src --> handlers["handlers/"]
  handlers --> getUser["getUser.mjs — GET /users/{userId}"]
  handlers --> createUser["createUser.mjs — POST /users"]
  handlers --> listUsers["listUsers.mjs — GET /users"]
  src --> shared["shared/"]
  shared --> db["database.mjs — Shared database utilities"]
  shared --> resp["response.mjs — Shared response helpers"]
  root --> tests["tests/"]
  tests --> unit["unit/getUser.test.mjs"]
  tests --> integration["integration/api.test.mjs"]
  root --> events["events/getUser.json — Test event for local invocation"]
  root --> pkg["package.json"]

---

SAM Template Anatomy

Global Section

Define default settings that apply to all functions:

Globals:
  Function:
    Runtime: nodejs20.x
    Timeout: 30
    MemorySize: 256
    Environment:
      Variables:
        TABLE_NAME: !Ref UsersTable
        LOG_LEVEL: info
    Tracing: Active
  Api:
    Cors:
      AllowOrigin: "'*'"
      AllowMethods: "'GET,POST,PUT,DELETE,OPTIONS'"
      AllowHeaders: "'Content-Type,Authorization'"

Function Resource

Resources:
  GetUserFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: src/handlers/getUser.handler
      Description: Retrieve a user by ID
      Policies:
        - DynamoDBReadPolicy:
            TableName: !Ref UsersTable
      Events:
        GetUser:
          Type: Api
          Properties:
            Path: /users/{userId}
            Method: get

API Resource

  ApiGateway:
    Type: AWS::Serverless::Api
    Properties:
      StageName: prod
      Auth:
        DefaultAuthorizer: CognitoAuthorizer
        Authorizers:
          CognitoAuthorizer:
            UserPoolArn: !GetAtt UserPool.Arn

DynamoDB Table

  UsersTable:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName: users
      BillingMode: PAY_PER_REQUEST
      AttributeDefinitions:
        - AttributeName: userId
          AttributeType: S
      KeySchema:
        - AttributeName: userId
          KeyType: HASH

---

SAM Policy Templates