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.
- Zero Compute (Functionless): Direct API Gateway service integration to DynamoDB (
GetItemfor lookups,UpdateItemwith 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 theDashboardUrlstack 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.
- Amazon API Gateway – REST API with VTL direct service integrations and resource policy authorization.
- Amazon DynamoDB – Fast NoSQL key-value store with TTL and GSI support.
- Amazon CloudFront – Edge CDN distribution for fast global redirects and caching.
- Amazon CloudWatch – Operational metrics and alarms.
- Amazon SNS – Notification topic for triggered alarms.
- AWS CLI (configured with appropriate deployment credentials)
- AWS SAM CLI v0.37.0+
- Make (for automated build and validation workflows)
For the first deployment, run the guided SAM deploy command:
make deploy-guidedOr deploy specifying a configuration environment:
sam deploy -g --config-file samconfig.toml --config-env prdDuring 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). |
## 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]: YNote
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 deployTo serve short links from your own domain (e.g. https://go.example.com/abc123):
- Request a certificate in
us-east-1. CloudFront only accepts ACM certificates fromus-east-1, regardless of the stack's region:Complete DNS validation and wait until the certificate status isaws acm request-certificate --region us-east-1 \ --domain-name go.example.com --validation-method DNS
ISSUED. - 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 - Point DNS at CloudFront. If
HostedZoneIdwas provided, Route 53 alias records are created for you. Otherwise, create aCNAMEforDomainAliaspointing to theDnsTargetstack output.
The ShortUrlBase stack output shows the base URL that short links are returned with.
| 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 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:Setaws 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=falseEnableCacheHitRateAlarm=trueonly if the main stack hasEnableCloudFrontAdditionalMetrics=true.
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 launchPrebuilt 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.
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/*"
]
}
]
}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/jsonAuthorization: AWS4-HMAC-SHA256 ...
{
"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 withhttp://orhttps://).ttl(integer, optional): Custom time-to-live in seconds from the current time. If omitted, uses stack default.
{
"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"
}Returned if the id already exists in DynamoDB:
{
"error": true,
"message": "URL link already exists"
}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"
}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.
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 registeredurlwithLocation: <destination_url>.- If the link ID does not exist, redirects to
Location: error?error=url_not_found.
# 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 cleanTo remove all deployed resources:
- Using SAM CLI:
sam delete --stack-name URLShortener
- Or via the AWS Management Console:
- Open the AWS CloudFormation Console.
- Select the stack named URLShortener (or your custom stack name).
- Click Delete and confirm.
- 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.
This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.