ShortURL - URL Shortening Service

A .NET Core URL shortening service with features like expiration, email notifications, and management.

🌐 Live Demo

Try it out: https://trimurl.sbs/

This repository contains the backend API that powers the live TrimURL service.

Features

• URL shortening with custom expiration times
• Email notifications for expired URLs
• Renewal functionality
• Database cleanup and monitoring
• AWS SQS integration for background processing
• Redis caching
• Zookeeper for distributed coordination

Quick Setup

1. Clone and Configure

git clone <your-repo-url>
cd ShortUrl

2. Configuration Setup

1. Copy the environment template:

   cp .env.example .env

2. Copy the settings templates:

   cp ShortURL/appsettings.template.json ShortURL/appsettings.json
   cp ShortURL/appsettings.Development.template.json ShortURL/appsettings.Development.json

3. Edit .env with your actual credentials and configuration

3. Required Services

You'll need to set up:

• MySQL Database - for data storage
• Redis - for caching
• Zookeeper - for distributed coordination
• AWS SQS - for background job processing
• Brevo Email Service - for email notifications

4. Environment Variables

Edit your .env file with these required values:

Variable	Description	Example
DB_HOST	MySQL host	localhost
DB_PASSWORD	MySQL password	your_password
BREVO_EMAIL_KEY	Brevo API key	xkeysib-...
WEB_URL	Your domain	https://yourdomain.com/
SQS_*_QUEUE	AWS SQS queue URLs	See .env.example

5. Run with Docker

docker-compose up -d

6. Run Locally

cd ShortURL
dotnet restore
dotnet run

API Endpoints

Base URL (Local Development): http://localhost:5000/

• POST /url - Create short URL
• GET /url/{shortUrl} - Redirect to original URL
• GET /url/{shortUrl}/info - Get URL information
• PATCH /url/{shortUrl}:renew - Extend URL expiration

Example Usage

# Create a short URL
curl -X POST https://trimurl.sbs/api/url \
  -H "Content-Type: application/json" \
  -H "X-User-Timezone: America/New_York" \
  -d '{"url": "https://example.com", "emailAddress": "user@example.com"}'

# Get URL info
curl https://trimurl.sbs/api/url/abc123/info

Development

Prerequisites

• .NET 8.0 or later
• MySQL
• Redis
• AWS account (for SQS)
• Brevo account (for emails)

Database Migrations

dotnet ef database update

Testing

dotnet test

Production Deployment

1. Set environment variables in your hosting platform
2. Configure your database connection
3. Set up AWS SQS queues
4. Configure email service
5. Deploy using your preferred method (Docker, Azure, AWS, etc.)

Production Service

This codebase powers the live URL shortening service at https://trimurl.sbs/.

Architecture & ID Generation

Detail Design Here

Snowflake ID Algorithm

This service uses a custom Snowflake-based ID generator optimized for URL shortening:

Configuration

• Worker ID Bits: 2 (supports 4 workers max)
• Sequence Bits: 2 (4 IDs per millisecond per worker)
• Timestamp: Unix milliseconds (remaining bits)

Capacity

• Per Worker: 4,000 IDs per second
• Total System: 16,000 IDs per second (4 workers)
• 8-character Base62: ~218 trillion possible combinations

ID Structure

[Timestamp: 59 bits][Worker ID: 2 bits][Sequence: 2 bits]

Base62 Encoding

Generated IDs are encoded using Base62 (0-9A-Za-z) to create short URLs:

• Character Set: 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
• Target Length: 8 characters
• Example: ID 123456789 → 8M0kX (Base62)

Why This Design?

1. Compact URLs: Base62 encoding produces short, readable URLs
2. High Availability: Distributed worker IDs via Zookeeper
3. No Collisions: Timestamp + Worker ID + Sequence ensures uniqueness
4. Scalable: Can handle high-traffic URL shortening demands
5. Time-ordered: IDs are roughly chronological for easier debugging

Distributed Coordination

• Zookeeper: Manages worker ID assignment across multiple instances
• Worker Assignment: Each pod/instance gets a unique worker ID (0-3)
• Failover: If a worker goes down, its ID can be reclaimed by new instances

URL Shortening Flow

1. Generate ID: Snowflake algorithm creates unique 64-bit ID
2. Encode: ID converted to Base62 string (~8 characters)
3. Store: Original URL mapped to short code in MySQL
4. Cache: Frequently accessed URLs cached in Redis
5. Serve: Short URL redirects to original URL