Skip to content

Latest commit

 

History

History
134 lines (93 loc) · 4.75 KB

README.md

File metadata and controls

134 lines (93 loc) · 4.75 KB
Raw

🔗 url-shortener

🧠 Rationale

This yet another url-shortener, is the one I'm using for AWS Security Digest Newsletter to track click rate from my readers.

I wasn't able to find an existing solution that match my needs so I crafted my own version, another excuse to learn something new 🤓.

Try out this AWS serverless url-shortener for your own usage and see the benefits it can bring.

It's perfect for shortening links and tracking analytics.

Plus, contributions and pull requests are welcome.

💡 Features

  1. Create API
  2. Companion static website (HTML + Javascript)
  3. Hits counter + Analytics (Persisted in DynamoDB)

🔋 Powered by

  • Lambda function (Python 🐍) + API Gateway
  • CloudFront + S3 + ACM
  • DynamoDB Table
  • CloudFormation + SAM

📐 Schema

Architecture Schema

🚀 Usage

Pre-requirements

  1. You will need to have an already issued AWS Certificate Manage (ACM) wildcard Certificate in us-east-1 AWS region: *.{your_domain}
  2. Configure the proper parameters in the Makefile like the Route53 hosted zone Id (HostedZoneId)

🎛 Parameters

Parameters Default Value Description
Product url-shortener Product Name
Project zophio Project Name
Environment dev Environment Name
MinChar 3 Minimum characters for the random shortened link id
MaxChar 3 Maximum characters for the random shortened link id
Domain zoph.io Desired Domain (must be linked to the HostedZoneId Parameter)
SubDomain shortener Desired subdomain of the API
HostedZoneId Required AWS Route53 HostedZoneId where your domain name belongs
FallbackUrl https://zoph.io When the url does not exist, fallback url
CertificateArn Required Arn of the Wildcard ACM Certificate (us-east-1)
AWSRegion eu-west-1 AWS Region
AlertsRecipient Required Email of the recipient of CloudWatch Alarms

Deployment

    $ make deploy
    $ make setup_front

How to shorten urls?

Using Companion Static Website

Go to the following website after the deployment (depends on your parameters 👆)

Demo:

DemoWebsite

  • https://short.{Domain}

Using the Makefile

    $ make url 'https://google.com'

ℹ️ Simple quotes are important

Using cURL

curl -X POST https://{subdomain}.{domain}/create/ \
--header "Content-Type: application/json" \
-d '{"long_url": "https://google.com"}'

Optionnaly, you can change the default TTL value (7 days), by using the ttl_in_days attribute in body request:

curl -X POST https://{subdomain}.{domain}/create/ \
--header "Content-Type: application/json" \
-d '{"long_url": "https://google.com", "ttl_in_days": 365}'

Optionnaly, you can ask for a human readable (false by default) short id, ie a suite of consonants/vowels, easier to read/remember.

curl -X POST https://{subdomain}.{domain}/create/ \
--header "Content-Type: application/json" \
-d '{"long_url": "https://google.com", "ttl_in_days": 3, "human_readable": true}'

Response:

{
  "short_id": "baho", 
  "created_at": "2024-08-24T15:28:04", 
  "ttl": 1724772484, 
  "short_url": "https://{subdomain}.{domain}/baho", 
  "long_url": "https://google.com"
}

Note: the generated short id is lowercase to avoid any human mistake.

Response sample
{
  "created_at": "2023-01-17T13:37:00",
  "long_url": "https://zoph.io",
  "short_id": "dBC",
  "short_url": "https://{subdomain}.{domain}/dBC",
  "ttl": 1674561936
}

📖 Reference