Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Serverless URL Shortener

A Serverless URL Shortener service which allows you to deploy a URL Shortener in AWS using Serverless Framework

For the following example domain of to genenerate short urls i.e.

Supports click analytics visualisations and downloadable CSVs

Technology Stack

  • Cloudfront
  • DynamoDB
  • Lambda
  • Route53
  • Cloudformation
  • Serverless Framework
  • Typescript
  • NodeJS




There are two options for deployment:


  • An ACM SSL Ceritificate in us-east-1 for - the ARN for the cerificate should be set as the ${acmcertarn} variable

If you require a DNS record to be create for your Cloudfront Distribution

  • A Route53 Hosted Zone ID set as the ${r53hostedzoneid} variable. e.g. Z2FDTNDATAQYW2

Without Route53 Record

npm install

serverless deploy --stage=${stage} --region=${region} --acmcertarn ${acmcertarn} --domainname ${domainname} --creatednsrecord "false"

The CloudFormation Stack outputs the CloudFront domain - direct your short Domain DNS record at this domain name

With Route53 Record

npm install

serverless deploy --stage=${stage} --region=${region} --acmcertarn ${acmcertarn} --domainname ${domainname} --r53hostedzoneid ${r53hostedzoneid} --creatednsrecord "true"


When the stack is deployed you will be provided an API key available in the API Gateway console called key-${stage}

Example CURL Request:

curl --location --request POST '' \
--header 'x-api-key: ${apikey}' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "longurl": ""


    "longurl": "",
    "id": "WKp5Ow",
    "created": 1613425012,
    "expire": 1621114612,
    "shorturl": ""

The response includes the following:

longurl : the long url provided

id : the generated short unique id for your short url

created : epoch timestamp of creation date

expire : the expiry of this url (short url will become unavailable after this date / time)

shorturl : the short url generated

Note: The default url expiry is set to now + 3 months. To override the expiry for the url - include this into the request as an epoch timestamp.

Example CURL Request with custom expiry:

curl --location --request POST '' \
--header 'x-api-key: ${apikey}' \
--header 'Content-Type: text/plain' \
--data-raw '{
  "longurl": "",
  "expire": 1621114612

This record will expire on Saturday, 15 May 2021 21:36:52

Note: Short urls will be cached by Cloudfront for 1 day which means your lambda function invoke / dynamodb get will be cached for a day.


To view analytics for the usage of your short urls - The Cloudfront console offers a view of:

  • Top URLs (Popular objects)
  • Devices
  • Browsers
  • Operating Systems
  • Locations


Devices Devices

Browsers Browsers

Operating Systems os

Locations os