CodeAlpha URL Shortener

A Flask backend project for shortening long URLs, redirecting visitors through short codes, and tracking how many times each short URL is used.

This project was built for the CodeAlpha Backend Development Internship.

Author

Ahmed Wael Salah Mohammed AlSheikh

Features

• Create short URLs from valid http or https links.
• Redirect short codes to the original URLs.
• Track click_count every time a short URL is visited.
• Use the optional browser frontend to shorten URLs from a simple page.
• Return clean JSON error responses for invalid input and missing short codes.
• Persist data with SQLite.
• Include pytest coverage for the API.

Tech Stack

• Python
• Flask
• Flask-SQLAlchemy
• SQLite
• python-dotenv
• pytest

Project Structure

CodeAlpha_URLShortener/
├── app/
│   ├── __init__.py
│   ├── extensions.py
│   ├── models.py
│   ├── routes.py
│   └── templates/
│       └── index.html
├── tests/
│   ├── conftest.py
│   └── test_routes.py
├── run.py
├── requirements.txt
├── pytest.ini
├── .gitignore
├── AGENTS.md
└── README.md

Setup

Create a fresh virtual environment:

python -m venv .venv

Activate the virtual environment on Linux or macOS:

source .venv/bin/activate

Activate the virtual environment on Windows PowerShell:

.venv\Scripts\Activate.ps1

Install dependencies:

.venv/bin/python -m pip install -r requirements.txt

This repository already uses SQLite by default. The database file is created at:

instance/urlshortener.sqlite

You can override the database with a .env file:

DATABASE_URL=sqlite:///instance/urlshortener.sqlite

Run the App

python run.py is intended for local development only. Debug mode is off by default. To enable Flask debug mode locally, set FLASK_DEBUG=true.

.venv/bin/python run.py

Optional debug mode:

FLASK_DEBUG=true .venv/bin/python run.py

The local API will be available at:

http://127.0.0.1:5000

The optional browser frontend is available at:

http://127.0.0.1:5000/

Open that page, enter a long http or https URL, and click Shorten to see the generated short URL.

Run Tests

After installing dependencies, run the test suite with:

.venv/bin/python -m pytest

If your virtual environment is missing test dependencies, reinstall them from the pinned requirements file:

.venv/bin/python -m pip install -r requirements.txt

API Endpoints

Health Check

GET /api/health

Example request:

curl http://127.0.0.1:5000/api/health

Expected response:

{
  "status": "ok"
}

Create a Short URL

POST /api/shorten

Request body:

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

Example request:

curl -X POST http://127.0.0.1:5000/api/shorten \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Expected response:

{
  "original_url": "https://example.com",
  "short_code": "abc123",
  "short_url": "http://127.0.0.1:5000/abc123"
}

Missing URL Error

Example request:

curl -X POST http://127.0.0.1:5000/api/shorten \
  -H "Content-Type: application/json" \
  -d '{}'

Expected response:

{
  "error": "A valid http or https URL is required."
}

Invalid URL Error

Example request:

curl -X POST http://127.0.0.1:5000/api/shorten \
  -H "Content-Type: application/json" \
  -d '{"url": "not-a-url"}'

Expected response:

{
  "error": "A valid http or https URL is required."
}

Redirect to the Original URL

GET /<short_code>

Example request:

curl -i http://127.0.0.1:5000/abc123

Expected response:

HTTP/1.1 302 FOUND
Location: https://example.com

Get Short URL Stats

GET /api/stats/<short_code>

Example request:

curl http://127.0.0.1:5000/api/stats/abc123

Expected response:

{
  "original_url": "https://example.com",
  "short_code": "abc123",
  "click_count": 1,
  "created_at": "2026-06-29T10:00:00.000000"
}

Short Code Not Found

Example request:

curl http://127.0.0.1:5000/api/stats/invalidcode

Expected response:

{
  "error": "short_code not found."
}

GitHub Submission Note

Before submitting to CodeAlpha:

1. Run .venv/bin/python -m pytest and confirm all tests pass.
2. Start the development app with .venv/bin/python run.py.
3. Manually test the API with the curl examples above.
4. Commit the final project files.
5. Push the repository to GitHub and submit the GitHub repository link.