🔗 Short URL

A lightweight URL shortening service built with Spring Boot 4.1.

This project demonstrates the implementation of a RESTful API using:

• Base62 encoding
• Cache Aside pattern with Redis
• PostgreSQL persistence
• Docker Compose
• Unit, Controller and Integration Tests with Testcontainers

 ┌─────────────┐
│ Client │
└──────┬──────┘
│
POST /shorten
GET /{code}
│
┌────────▼────────┐
│ Spring Boot API │
└────────┬────────┘
│
┌─────────┴─────────┐
▼ ▼
PostgreSQL Redis
Persistent Store Cache

---

Example

The following example shows the complete request flow:

1. Create a shortened URL
2. Access the generated short URL
3. Receive an HTTP 302 redirect
4. Observe the Cache-Aside flow (Redis → PostgreSQL → Redis)

---

Architecture

Component Diagram - URL Shortening Flow

flowchart LR
Client[Client]
subgraph App[Spring Boot Application]
Controller[UrlController]
Service[UrlShortenerService]
Repository[ShortUrlRepository]
Encoder[Base62Encoder]
end
DB[(PostgreSQL)]
Redis[(Redis)]
Client -->|POST /shorten| Controller
Controller -->|call| Service
Service -->|read / write| Repository
Repository -->|SQL| DB
Service -->|Generate Base62 code| Encoder
Service -.->|not used| Redis

Loading

URL Shortening Sequence:

sequenceDiagram
participant Client
participant Controller
participant Service
participant PostgreSQL
Client->>Controller: POST /shorten
Controller->>Service: shorten(url)
Service->>PostgreSQL: URL already exists?
alt Yes
PostgreSQL-->>Service: existing code
else No
Service->>Service: generate Base62 code
Service->>PostgreSQL: persist URL
end
Service-->>Controller: shortUrl
Controller-->>Client: 200 OK

Loading

URL Redirect Flow (Cache Aside)

sequenceDiagram
participant Client
participant Service
participant Redis
participant PostgreSQL
Client->>Service: GET /{code}
Service->>Redis: query
alt Cache HIT
Redis-->>Service: URL
else Cache MISS
Service->>PostgreSQL: query
PostgreSQL-->>Service: URL
Service->>Redis: update cache
end
Service-->>Client: 302 Redirect

Loading

---

Technologies

• Java 21
• Spring Boot 4.1
• Spring MVC
• Spring Data JPA
• Spring Data Redis
• PostgreSQL
• Redis
• Docker Compose
• JUnit 5
• Mockito
• MockMvc
• WebTestClient
• Testcontainers

---

Project Structure:

src
main
├── config
├── controller
├── dto
├── entity
├── repository
├── service
└── util
test
├── controller
├── integration
└── service

---

Getting Started:

# Clone the Repository
git clone https://github.com/wekers/shortURL.git
cd shortURL/

Copy the example environment file:

cp .env.example .env

Edit the .env file if you wish to change the PostgreSQL credentials.

Starting the infrastructure

docker compose --env-file .env up -d

Check containers:

docker ps

Running the application

Load the environment variables:

• For Bash/Zsh:

export$(grep -v '^#' .env | xargs)

• For Fish shell (use a helper file):

source load-env.fish

Run the application:

./mvnw spring-boot:run

Redis Insight

Redis Stack Web UI:

http://localhost:8001

Endpoints

Shorten URL

curl -X POST http://localhost:8080/shorten \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/products/electronics/notebooks/gaming/high-performance-model-2026"}'

Response:

{
"shortUrl": "http://localhost:8080/fxSM"
}

Redirect to Original URL

curl -v http://localhost:8080/fxSM

Response:

HTTP/1.1 302 Found
Location: https://example.com/products/electronics/notebooks/gaming/high-performance-model-2026

---

Testing

./mvn test

Type	Frameworks
Unit	JUnit + Mockito
Controller	MockMvc
Integration	WebTestClient + Testcontainers (PostgreSQL + Redis)

Roadmap

• URL Shortening
• PostgreSQL
• Redis
• Docker Compose
• Unit Tests
• Controller Tests
• Integration Tests
• Testcontainers
• GitHub Actions
• Build Badge

Future Improvements

• API documentation (OpenAPI / Swagger)
• Metrics with Micrometer + Prometheus
• Docker image publishing
• Deployment to a cloud provider

License

MIT