minxa.lol URL Shortener

minxa.lol is a lightweight and efficient URL shortening service built with FastAPI, SQLAlchemy, and Hashids. It converts long URLs into short, shareable codes and provides redirection to the original URLs.

Features

🔗 Shorten URLs into unique shortcodes
🚀 Redirect to original URLs using the shortcode
✅ Validates shortcode format
🛠 Built with modern async Python stack
🧂 Configurable encoding via hashids

Tech Stack

FastAPI
SQLAlchemy (async + sync)
PostgreSQL
Hashids
Alembic (for migrations)
Pydantic / Pydantic Settings
Uvicorn (ASGI server)

Getting Started

1. Clone the repository

git clone https://github.com/yourusername/minxa.git
cd minxa

2. Create and configure your environment file

Copy the example file and update it with your local settings:

cp .env.example .env

Required variables in .env:

DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/minxa
ENVIRONMENT=dev
HASHIDS_SALT=your-secret-salt
ENCODER_ALPHABET=abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890

3. Install dependencies

pip install -r requirements.txt

4. Run the application

uvicorn app.main:app --reload

API Endpoints

`POST /`

Create a new shortened URL.

Request Body:

{
  "url": "https://example.com"
}

Response:

{
  "shortcode": "abc123",
  "url": "https://example.com"
}

`GET /{shortcode}`

Redirects to the original URL associated with the given shortcode.

Example:

curl -v http://localhost:8000/abc123

Returns a 302 redirect to the original URL.

Project Structure

app/
├── main.py               # FastAPI entry point
├── config.py             # Environment and settings
├── database.py           # Database setup
├── models/               # SQLAlchemy models
├── routes/               # API endpoints
├── services/             # URL logic
├── schemas/              # Pydantic schemas
├── utils/                # Encoder logic using hashids
├── exceptions.py         # Custom exceptions

Development Notes

Database tables auto-create in development mode
Encoder uses Hashids for deterministic, unique shortcodes
Uses pydantic for validation and FastAPI's dependency injection
Alembic is available for database migrations

2.4 KiB Raw Blame History