Skip to content

README.md

Latest commit

 

History

History
412 lines (298 loc) · 11 KB

README.md

File metadata and controls

412 lines (298 loc) · 11 KB

Spring Boot Random User API

Java Spring Boot PostgreSQL License

A REST API built with Spring Boot that fetches users from DummyJSON Users API and stores them in PostgreSQL.

Quick Start • API Docs • Architecture

📦 Prerequisites

  • Java 25+
  • Docker Desktop
  • Maven (wrapper included)

🚀 Quick Start

# 1. Clone
git clone https://github.com/XPEHO/spring_boot_java_random_user.git
cd spring_boot_java_random_user

# 2. Configure environment
cp .env.template .env
# Edit .env with your credentials

# 3. Start PostgreSQL
docker-compose up -d

# 4. Run application
./mvnw spring-boot:run

Access:

⚙️ Configuration

Environment Variables (.env)

POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password
POSTGRES_DB=your_database
POSTGRES_PORT=5432

External API Configuration

application.properties uses:

dummy.api.base-url=https://dummyjson.com/

Profiles

  • default: PostgreSQL (production)
  • local: Custom local settings
  • test: H2 in-memory database

📖 API Documentation

Interactive Docs: http://localhost:8080/api
OpenAPI Spec: http://localhost:8080/v3/api-docs

Endpoints

Method Path Description Status
GET /random-users?page=1&size=10&source=DUMMY Fetch and save users from selected external API source ✅
GET /random-users/{id} Get user by ID ✅
POST /random-users Create a new user ✅
PUT /random-users/{id} Update user ✅
DELETE /random-users/{id} Delete user ✅
GET /random-users/filter Filter users by criteria ✅

Example Request

# Fetch 10 users from external API and store them
curl -X GET "http://localhost:8080/random-users?page=1&size=10&source=DUMMY"

# Fetch 10 users from randomuser.me and store them
curl -X GET "http://localhost:8080/random-users?page=1&size=10&source=RANDOM_USER"

# Get user by ID
curl -X GET "http://localhost:8080/random-users/1"

# Create user
curl -X POST "http://localhost:8080/random-users" \
  -H "Content-Type: application/json" \
  -d '{
    "gender": "female",
    "firstname": "Jane",
    "lastname": "Doe",
    "civility": "Ms",
    "email": "jane@example.com",
    "phone": "0600000000",
    "picture": "pic.jpg",
    "nat": "FR"
  }'

# Filter users by gender and nationality
curl -X GET "http://localhost:8080/random-users/filter?gender=MALE&nat=FR"

# Filter users by firstname (partial match, case-insensitive)
curl -X GET "http://localhost:8080/random-users/filter?firstname=john"

# Update user
curl -X PUT "http://localhost:8080/random-users/1" \
  -H "Content-Type: application/json" \
  -d '{
    "gender": "male",
    "firstname": "John",
    "lastname": "Smith",
    "civility": "Mr",
    "email": "john@example.com",
    "phone": "0611111111",
    "picture": "pic2.jpg",
    "nat": "US"
  }'

🧪 Testing

# Run all tests with Docker
./mvnw verify

# Unit tests only
./mvnw test

# With coverage report (target/site/jacoco/index.html)
./mvnw clean verify

#cucumber tests
./mvnw verify -DskipDocker=true -Dit.test=CucumberIntegrationTest

Test Stack:

  • JUnit 5 - Testing framework
  • Mockito - Mocking
  • JaCoCo - Code coverage
  • Cucumber - BDD

🏗️ Architecture

Clean Architecture (3 Layers)

┌─────────────────────────────────────┐
│     Presentation Layer              │  ← REST Controllers
│  (controllers, handlers)            │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│     Domain Layer                    │  ← Business Logic
│  (usecases, entities, exceptions)   │
└─────────────────────────────────────┘
              ↓
┌─────────────────────────────────────┐
│     Data Layer                      │  ← Data Access
│  (repositories, services, sources)  │
└─────────────────────────────────────┘
              ↓
         PostgreSQL

Domain Service Ports

  • LocalUserService: local persistence operations (save, read, delete) backed by PostgreSQL.
  • RemoteUserService: external user source contract used by use cases.

External Source Adapter

  • DummyUserApi: Retrofit client contract for DummyJSON endpoints.
  • DummyUserServiceImpl: adapter that calls DummyUserApi, maps DTOs, and returns PaginatedUsers.
  • RandomUserApi: Retrofit client contract for randomuser.me endpoints.
  • RandomUserServiceImpl: adapter that calls RandomUserApi, maps DTOs, and returns PaginatedUsers.

Project Structure

src/main/java/com/xpeho/spring_boot_java_random_user/
├── SpringBootJavaRandomUserApplication.java  ← Entry point
├── config/                                    ← Configuration
├── presentation/                              ← REST API Layer
│   ├── controllers/                           ← API interfaces
│   └── handlers/                              ← Implementations
├── domain/                                    ← Business Layer
│   ├── entities/                              ← Domain models
│   ├── exceptions/                            ← Custom exceptions
│   ├── services/                              ← Business services
│   └── usecases/                              ← Use cases
└── data/                                      ← Data Layer
    ├── converters/                            ← DTO/Entity mapping
    ├── models/                                ← Data models
    ├── services/                              ← Data services
    └── sources/                               ← API & DB access

🗄️ Database Schema

Users Table

Column Type Description
id SERIAL PRIMARY KEY Auto-incremented identifier
gender VARCHAR(20) Gender
firstname VARCHAR(100) First name
lastname VARCHAR(100) Last name
civility VARCHAR(20) Title (Mr, Ms, Mrs, etc.)
email VARCHAR(255) Email address
phone VARCHAR(50) Phone number
picture VARCHAR(500) Avatar/picture URL
nat VARCHAR(10) Nationality code

Liquibase Migrations

Database schema is managed with Liquibase. Migrations are applied automatically on application startup.

src/main/resources/db/changelog/
├── db.changelog-master.yaml          ← Index file
└── changes/
    └── 001-create-users-table.yaml   ← Table creation

CLI Commands:

./mvnw liquibase:status                              # View pending changes
./mvnw liquibase:update                              # Apply migrations
./mvnw liquibase:rollback -Dliquibase.rollbackCount=1  # Rollback last change

📊 Monitoring

Actuator Endpoints

Available Metrics: JVM metrics, HTTP metrics, Database connection pool metrics

🔍 Quality & CI/CD

SonarQube Analysis

./mvnw clean verify sonar:sonar

GitHub Actions

Workflow: .github/workflows/sonar.yaml

Triggers: Push to any branch, Pull requests

Pipeline:

  1. Sets up Java 25
  2. Runs Maven tests with code coverage
  3. Uploads results to SonarQube
  4. Waits for quality gate

Required Secrets:

  • SONAR_TOKEN - SonarQube authentication
  • SONAR_HOST_URL - SonarQube instance URL
  • POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, POSTGRES_PORT

❌ Troubleshooting

DataSource Configuration Error

Error:

Failed to configure a DataSource: 'url' attribute is not specified
and no embedded datasource could be configured.

Solution: Ensure spring.datasource.url is set in application.properties or environment variables.

PostgreSQL Connection Failed

Error:

org.postgresql.util.PSQLException: Connection to localhost:5432 refused

Solution:

# Check if Docker is running
docker ps

# Start PostgreSQL
docker-compose up -d

# Verify connection
psql -U postgres -h localhost

Tests Fail with H2

Error:

Circular placeholder reference in application-test.properties

Solution: Use the corrected application-test.properties with H2 configuration:

spring.datasource.url=jdbc:h2:mem:testdb
spring.datasource.driver-class-name=org.h2.Driver

Java Version Not Supported

Error:

error: release version 25 not supported

Solution:

  • Install Java 25 or later
  • Update Maven compiler plugin version in pom.xml

🌐 External API

This project integrates with DummyJSON Users API:

👥 Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

👤 Author

XPEHO - GitHub Organization

🔗 Useful Links

Made with ❤️ by XPEHO

⭐ If you found this helpful, please consider starring the repository!