Skip to content

README.md

Latest commit

 

History

History
182 lines (123 loc) · 3.17 KB

README.md

File metadata and controls

182 lines (123 loc) · 3.17 KB

URL Shortener API

Overview

This project is a containerized backend service that generates shortened URLs and redirects users to the original destination. The service is built using FastAPI and PostgreSQL and is deployed using Docker and Docker Compose.

The application demonstrates backend development concepts such as REST API design, database integration, containerization, and service orchestration.

Features

  • Generate short URLs from long URLs
  • Redirect users to the original URL using the short code
  • Persistent storage using PostgreSQL
  • Automatic API documentation with Swagger
  • Dockerized environment for consistent development and deployment

Technology Stack

Backend Framework: FastAPI Language: Python Database: PostgreSQL ORM: SQLAlchemy Containerization: Docker Service Orchestration: Docker Compose

Project Structure

url-shortener
│
├── app
│   ├── main.py
│   ├── database.py
│   ├── models.py
│   ├── schemas.py
│   ├── crud.py
│   └── utils.py
│
├── requirements.txt
├── Dockerfile
└── docker-compose.yml

System Architecture

The application runs two services inside Docker containers.

FastAPI Service Handles API requests and business logic.

PostgreSQL Service Stores shortened URLs and related data.

The FastAPI service communicates with the PostgreSQL container through Docker's internal network.

Setup Instructions

1. Clone the Repository

git clone <repository-url>
cd url-shortener

2. Build and Start the Containers

docker compose up --build

Docker Compose will start two containers:

  • FastAPI backend
  • PostgreSQL database

3. Access the API

Once the containers are running, open the API documentation:

http://localhost:9003/docs

Swagger UI allows you to test the endpoints interactively.

API Endpoints

Create Short URL

POST /shorten

Request Body

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

Response

{
  "short_code": "aB92xY",
  "original_url": "https://example.com"
}

Redirect to Original URL

GET /{short_code}

Example

http://localhost:8000/aB92xY

The server redirects the user to the stored original URL.

Database Configuration

The PostgreSQL database is configured in the Docker Compose file.

POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=shortener

Connection string used by the application:

postgresql://postgres:postgres@db:5432/shortener

Testing the API

Using Swagger

Open:

http://localhost:8000/docs

Test the endpoints directly from the interactive documentation.

Using curl

Create a short URL:

curl -X POST "http://localhost:9003/shorten" \
-H "Content-Type: application/json" \
-d '{"original_url":"https://google.com"}'

Using Postman

Send a POST request to:

http://localhost:9003/shorten

with a JSON body containing the original URL.

Future Improvements

Possible enhancements include:

  • URL click analytics
  • Custom short codes
  • URL expiration
  • User authentication
  • Rate limiting
  • Redis caching for faster redirects

License

This project is intended for educational and demonstration purposes.