Skip to content

README.md

Latest commit

 

History

History
87 lines (69 loc) · 3.08 KB

README.md

File metadata and controls

87 lines (69 loc) · 3.08 KB
Raw

URL Shortener API (FastAPI + SQLAlchemy + Alembic)

This project is a URL shortener service built with FastAPI. It supports random and custom short keys, redirect forwarding, a peek endpoint, admin links, click tracking, and soft deactivation.

Current Features

  • Create shortened URLs from target URLs.
  • Optional custom URL keys.
  • Redirect from short key to target URL.
  • Graceful forward check before redirect.
  • Peek endpoint to inspect a short key target.
  • Admin info endpoint using secret key.
  • Soft-deactivate shortened URLs.
  • Click count tracking.
  • Pydantic v2 schemas with from_attributes.
  • Alembic migration support.

Project Structure

  • shortener_app/main.py: FastAPI routes and request handling.
  • shortener_app/crud.py: Database operations.
  • shortener_app/models.py: SQLAlchemy ORM models.
  • shortener_app/schemas.py: Request and response schemas.
  • shortener_app/database.py: Engine, sessionmaker, and declarative base.
  • shortener_app/config.py: Environment-based settings.
  • alembic.ini: Alembic configuration.
  • alembic/env.py: Alembic metadata wiring.

Environment Variables

Recommended .env format:

ENV_NAME=development BASE_URL=http://127.0.0.1:8000 DB_URL=sqlite:///./shortener_app.db

Quick Start

  1. Create and activate virtual environment.
  2. Install dependencies: pip install fastapi uvicorn sqlalchemy alembic pydantic-settings validators
  3. Apply migrations: python -m alembic upgrade head
  4. Run the app: uvicorn shortener_app.main:app --reload

API Docs

Main Endpoints

  • GET /: Welcome endpoint.
  • POST /url: Create short URL (optional custom_key).
  • GET /peek/{url_key}: View key -> target mapping.
  • GET /{url_key}: Redirect to target URL.
  • GET /admin/{secret_key}: Get admin info for a shortened URL.
  • DELETE /admin/{secret_key}: Deactivate shortened URL.

Testing Notes

  • Redirect endpoints may show "Failed to fetch" in Swagger due to browser CORS behavior on cross-origin redirects.
  • Test redirect behavior with browser navigation or curl instead: curl -i http://127.0.0.1:8000/<url_key> curl -L -i http://127.0.0.1:8000/<url_key>

Production-Readiness Improvements

  1. Switch SQLite to PostgreSQL for better concurrency and durability.
  2. Add transaction rollback handling around commit failures.
  3. Return 409 Conflict for duplicate custom keys.
  4. Add request logging, structured logs, and correlation IDs.
  5. Add rate limiting on create, peek, and forward endpoints.
  6. Add authentication and authorization for admin endpoints.
  7. Add URL safety controls (blocklists, allowlists, malware screening).
  8. Add caching (for hot key lookups) with Redis.
  9. Add observability: metrics, tracing, health and readiness probes.
  10. Add test suites: unit, integration, and API contract tests.
  11. Add CI pipeline for linting, testing, migration checks, and security scans.
  12. Add containerization and deployment configuration.
  13. Define standardized error response schema across the API.
  14. Add background jobs for analytics and periodic link checks.
  15. Consider async migration after measuring load and bottlenecks.