Skip to content

About

100% functionless URL shortener on AWS - no Lambda, no containers. API Gateway VTL mapping templates talks natvely to DynamoDB, with IAM auth, AWS Organizations scoping, CloudFront edge caching, and TTL-based link expiry.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Functionless URL Shortener

Latest Release License: Apache 2.0 CI/CD Ask DeepWiki Security Policy

A high-performance, cost-effective URL shortener built completely without compute (no AWS Lambda functions). All routing and business logic are handled directly at the Amazon API Gateway layer via Velocity Template Language (VTL) mapping templates that communicate natively with Amazon DynamoDB.

The administrative endpoints are secured using AWS IAM Authentication (SigV4) and restricted to accounts within a specific AWS Organization via API Gateway Resource Policies. Public URL redirection is accelerated through Amazon CloudFront.


Architecture & Features

  • Zero Compute (Functionless): Direct API Gateway service integration to DynamoDB (GetItem for lookups, UpdateItem with conditional checks for creating links).
  • IAM & AWS Organizations Security: Management endpoints (/api/*) require AWS SigV4 signed requests and are restricted to identities belonging to your specified AWS Organization ID (aws:PrincipalOrgID).
  • Public High-Speed Redirects: Public endpoints (/{linkId} and /?go={linkId}) perform fast HTTP 301 redirects directly from DynamoDB lookups, cached at the edge with CloudFront.
  • Automatic Expiration (TTL): Built-in DynamoDB Time-To-Live support automatically cleans up expired links.
  • Traffic Dashboard: An optional Amazon CloudWatch dashboard (EnableDashboard, on by default) showing CloudFront requests and error rates, API Gateway volume and latency, DynamoDB capacity and throttles, and alarm status. Its link is in the DashboardUrl stack output.
  • Observability & Alerting: Comprehensive Amazon CloudWatch alarms configured for API Gateway (4xx, 5xx, p99 Latency), DynamoDB (User/System Errors), and CloudFront (Error Rate, Cache Hit Rate), notifying an Amazon SNS topic.

Services Used


Requirements for Deployment

  • AWS CLI (configured with appropriate deployment credentials)
  • AWS SAM CLI v0.37.0+
  • Make (for automated build and validation workflows)

Deployment

Guided Deployment

For the first deployment, run the guided SAM deploy command:

make deploy-guided

Or deploy specifying a configuration environment:

sam deploy -g --config-file samconfig.toml --config-env prd

Configuration Parameters

During the guided deployment, SAM CLI will prompt for the following parameters:

Parameter Required Default Description
Stack Name Yes URLShortener The name of the CloudFormation stack.
AWS Region Yes ap-south-1 The AWS region to deploy into.
AppName No shortener Application name prefix (must be globally unique, no spaces).
OrgId Yes (None) Your AWS Organization ID (e.g. o-xxxxxxxxxx) used to restrict IAM access on /api/*.
CustomDomainName No "" Optional URL prefix used to format short URLs returned by the API (e.g. https://sho.rt). Defaults to https://<DomainAlias> when DomainAlias is set.
DomainAlias No "" Optional custom hostname served by CloudFront (e.g. go.example.com). Requires AcmCertificateArn.
AcmCertificateArn Conditional "" ACM certificate ARN in us-east-1 covering DomainAlias. Required when DomainAlias is set.
EnableDashboard No true Create a CloudWatch dashboard for link traffic and service health.
AlarmEmail No "" Email address subscribed to alarm notifications (confirm the SNS email after deploy).
EnableCloudFrontAdditionalMetrics No false Enable CloudFront additional metrics (needed for CacheHitRate and its alarm); billed as CloudWatch custom metrics.
HostedZoneId No "" Optional Route 53 hosted zone ID. When set, alias A/AAAA records for DomainAlias are created automatically.
TTL No 31536000 Default URL lifespan in seconds (default is 1 year).

Example Interactive Prompt

## The name of the CloudFormation stack
Stack Name [URLShortener]: 

## The region you want to deploy in
AWS Region [ap-south-1]: 

## The name of the application (lowercase no spaces). This must be globally unique
Parameter AppName [shortener]: 

## AWS OrgId to protect APIs using IAM Auth to only accounts related to AWS Org
Parameter OrgId []: o-xxxxxxxxxx

## Domain Name for the shortener (optional)
Parameter CustomDomainName []: https://sho.rt

## TTL time for url to be active in seconds
Parameter TTL [31536000]: 

## Shows you resource changes to be deployed and requires a 'Y' to initiate deploy
Confirm changes before deploy [y/N]: y

## SAM needs permission to be able to create roles to connect to the resources in your template
Allow SAM CLI IAM role creation [Y/n]: Y

## Save your choices for later deployments
Save arguments to samconfig.toml [Y/n]: Y

Note

Creating or updating the Amazon CloudFront distribution may take a few minutes. Subsequent deployments with unchanged CloudFront settings will be significantly faster.

After the initial setup, you can re-deploy anytime using:

make deploy

Custom Domain

To serve short links from your own domain (e.g. https://go.example.com/abc123):

  1. Request a certificate in us-east-1. CloudFront only accepts ACM certificates from us-east-1, regardless of the stack's region:
    aws acm request-certificate --region us-east-1 \
      --domain-name go.example.com --validation-method DNS
    Complete DNS validation and wait until the certificate status is ISSUED.
  2. Deploy with the custom domain parameters:
    sam deploy --parameter-overrides \
      OrgId=o-xxxxxxxxxx \
      DomainAlias=go.example.com \
      AcmCertificateArn=arn:aws:acm:us-east-1:111122223333:certificate/xxxx \
      HostedZoneId=Z0123456789ABCDEFGHIJ   # optional
  3. Point DNS at CloudFront. If HostedZoneId was provided, Route 53 alias records are created for you. Otherwise, create a CNAME for DomainAlias pointing to the DnsTarget stack output.

The ShortUrlBase stack output shows the base URL that short links are returned with.


Monitoring & Alarms

Alarm Metric Fires when
<Stack> API 4xx / API 5xx AWS/ApiGateway 4XXError / 5XXError (ApiName=<Stack>-api, Stage=Prod) Error rate (Average) > 1% over 1 min
<Stack> API Latency AWS/ApiGateway Latency p99 > 75 ms over 5 min
<Stack> DynamoDB SystemErrors AWS/DynamoDB SystemErrors summed over GetItem, UpdateItem, DeleteItem ≥ 1 error/min in 2 of 5 minutes
<Stack> CloudFront Error Rate AWS/CloudFront TotalErrorRate (Region=Global) Average > 5% over 5 min
<Stack> CloudFront Cache Hit Rate (opt-in) AWS/CloudFront CacheHitRate (additional metric) Average ≤ 80% for 15 min

Regional alarms notify the AlarmTopicArn output topic; set AlarmEmail to subscribe an address. Missing data (no traffic) is treated as OK.

CloudFront alarms (us-east-1)

CloudFront publishes metrics only in us-east-1, so its alarms live in cloudfront-alarms.yaml, with their own SNS topic in that region.

  • Main stack in us-east-1: created automatically as a nested stack, notifying the main topic.
  • Main stack in any other region: deploy the alarms yourself in us-east-1:
    aws cloudformation deploy --region us-east-1 \
      --stack-name URLShortener-cloudfront-alarms \
      --template-file cloudfront-alarms.yaml \
      --parameter-overrides \
        DistributionId=<CloudFrontDistributionId output> \
        AlarmNamePrefix=URLShortener \
        AlarmEmail=ops@example.com \
        EnableCacheHitRateAlarm=false
    Set EnableCacheHitRateAlarm=true only if the main stack has EnableCloudFrontAdditionalMetrics=true.

Admin CLI (shorten)

Manage links without hand-crafting SigV4 requests using shorten, which now lives in its own repository:

go install github.com/divmora/functionless-url-shortener-cli/cmd/shorten@latest
shorten create https://example.com/very/long/path --id launch

Prebuilt binaries are attached to its releases. It reads the endpoint from this stack's ManagementApiEndpoint output.

Note

go install github.com/divmora/functionless-url-shortener/cmd/shorten@v0.4.0 still installs the version that shipped in this repository's v0.4.0 release.


IAM Permissions

Clients calling the secured management endpoints (/api/*) require an IAM principal belonging to the configured AWS Organization with the following least-privilege policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowURLShortenerManagementAPI",
            "Effect": "Allow",
            "Action": [
                "execute-api:Invoke"
            ],
            "Resource": [
                "arn:aws:execute-api:*:*:*/*/POST/api",
                "arn:aws:execute-api:*:*:*/*/GET/api/*",
                "arn:aws:execute-api:*:*:*/*/DELETE/api/*"
            ]
        }
    ]
}

API Reference

1. Create a Short URL

Creates a new short URL record in DynamoDB. Returns an error if the ID already exists.

  • Endpoint: POST /api
  • Authentication: AWS SigV4 (IAM) + AWS Organization check (aws:PrincipalOrgID)
  • Headers:
    • Content-Type: application/json
    • Authorization: AWS4-HMAC-SHA256 ...

Request Body

{
  "id": "my-custom-slug",
  "url": "https://example.com/very/long/destination/url",
  "ttl": 604800
}
  • id (string, required): The unique short identifier.
  • url (string, required): The destination URL (must start with http:// or https://).
  • ttl (integer, optional): Custom time-to-live in seconds from the current time. If omitted, uses stack default.

Response (200 OK)

{
  "id": "my-custom-slug",
  "url": "https://example.com/very/long/destination/url",
  "shortUrl": "https://sho.rt/?go=my-custom-slug",
  "timestamp": "2026-08-20T08:30:00.000Z",
  "owner": "AROAEXAMPLEUSER:session-name"
}

Error Response (422 Unprocessable Entity)

Returned if the id already exists in DynamoDB:

{
  "error": true,
  "message": "URL link already exists"
}

2. Get Link Details

Fetches metadata for an existing short link.

  • Endpoint: GET /api/{linkId}
  • Authentication: AWS SigV4 (IAM) + AWS Organization check (aws:PrincipalOrgID)
  • Response (200 OK):
{
  "id": "my-custom-slug",
  "url": "https://example.com/very/long/destination/url",
  "shortUrl": "https://sho.rt/?go=my-custom-slug",
  "timestamp": "2026-08-20T08:30:00.000Z",
  "owner": "AROAEXAMPLEUSER:session-name"
}

3. Delete a Short URL

Deletes an existing short link and returns the deleted record.

  • Endpoint: DELETE /api/{linkId}
  • Authentication: AWS SigV4 (IAM) + AWS Organization check (aws:PrincipalOrgID)
  • Response (200 OK):
{
  "id": "my-custom-slug",
  "url": "https://example.com/very/long/destination/url",
  "owner": "AROAEXAMPLEUSER:session-name"
}
  • Response (404 Not Found) if the link does not exist:
{ "error": true, "message": "URL link not found" }

Note

CloudFront caches redirects for up to 5 minutes (Cache-Control: max-age=300), so a deleted link may keep redirecting briefly unless you create a CloudFront invalidation.


4. URL Redirection (Public)

Performs an HTTP 301 redirect to the destination URL. No authentication required.

  • Endpoints:
    • GET /{linkId}
    • GET /?go={linkId}
  • Responses:
    • 301 Moved Permanently: Redirects to the registered url with Location: <destination_url>.
    • If the link ID does not exist, redirects to Location: error?error=url_not_found.

Development & Building

Common Commands

# Validate SAM template and OpenAPI definitions
make validate

# Build SAM application
make build

# Guided interactive deployment
make deploy-guided

# Deploy with existing samconfig.toml
make deploy

# Clean temporary build artifacts
make clean

Cleanup

To remove all deployed resources:

  1. Using SAM CLI:
    sam delete --stack-name URLShortener
  2. Or via the AWS Management Console:

Community & Contributing

  • Contributing Guide: Review contribution guidelines, development workflows, and Conventional Commit requirements.
  • Product Roadmap: View planned architectural vision, edge optimizations, and upcoming capabilities.
  • Code of Conduct: Contributor Covenant Code of Conduct.
  • Security Policy: Guidelines for reporting security vulnerabilities responsibly.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

About

100% functionless URL shortener on AWS - no Lambda, no containers. API Gateway VTL mapping templates talks natvely to DynamoDB, with IAM auth, AWS Organizations scoping, CloudFront edge caching, and TTL-based link expiry.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages