🚀 Learning REST APIs with Spring Boot

A clean, industry-grade REST API built using Spring Boot, designed with real-world backend engineering practices — not tutorial shortcuts.

This repository serves as both a learning resource and a production-quality reference for building scalable, maintainable REST APIs.

---

👔 Recruiter / Hiring Manager?
Prefer a fast overview instead of full documentation?
👉 Click here for the Recruiter-Optimized README

---

📌 Project Goals

Most beginner Spring Boot projects:

• Mix layers and responsibilities
• Ignore REST semantics
• Skip validation and error contracts
• Fail under real data conditions

This project focuses on:

• Clean layered architecture
• Strict REST conventions (PUT vs PATCH)
• Database-backed persistence
• Predictable, standardized API behavior
• Code that scales without rewrites

---

🧱 Architecture Overview

Client
  ↓
Controller  →  Service  →  Repository  →  Database
     ↑             ↓
   DTOs        Business Logic

Design Principles

• Stateless REST API
• DTO-based API boundaries
• Centralized exception handling
• Database as the single source of truth

---

🛠️ Tech Stack

Layer	Technology
Language	Java 23
Framework	Spring Boot 4.0.2
ORM	Spring Data JPA (Hibernate)
Database	PostgreSQL
Build Tool	Maven
API Testing	Postman
DB Tool	DBeaver
IDE	IntelliJ IDEA

---

📂 Project Structure

src/main/java
└── com.darkgod.springboot.LearningRESTAPIs
    ├── controller        # REST endpoints
    ├── service           # Business logic
    ├── service.impl      # Service implementations
    ├── repository        # JPA repositories
    ├── entity            # JPA entities
    ├── dto               # Request / Response models
    ├── api               # API response contracts
    └── exception_handler # Centralized exception handling

---

🌐 API Endpoints

Base URL:

/api/v1/students

Method	Endpoint	Description
POST	/	Create student
GET	/{id}	Get student by ID
GET	/	Get all students
PUT	/{id}	Full update (replace)
PATCH	/{id}	Partial update
DELETE	/{id}	Delete student

---

📦 API Response Format

✅ Success Response

{
  "data": { },
  "message": "Operation successful"
}

❌ Error Response

{
  "timestamp": "2026-02-05T22:13:52",
  "status": 404,
  "error": "NOT_FOUND",
  "message": "Student not found",
  "path": "/api/v1/students/10"
}

---

🔐 Validation & Error Handling

• Bean Validation (@Valid)
• Proper HTTP status codes (400, 404, 409, 500)
• No try/catch blocks in controllers
• Centralized error handling using @RestControllerAdvice

---

🗄️ Database Configuration

spring.datasource.url=jdbc:postgresql://localhost:5432/studentDB
spring.datasource.username=postgres
spring.datasource.password=your_password

spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

---

▶️ Running the Project

git clone https://github.com/<your-username>/learning-rest-apis-springboot.git
cd learning-rest-apis-springboot
mvn spring-boot:run

Application runs at:

http://localhost:8080

---

🧠 Learning Outcomes

• Real REST API design
• PUT vs PATCH semantics
• DTO vs Entity separation
• Hibernate persistence behavior
• Database-first debugging mindset

---

🛣️ Roadmap

• Pagination & sorting
• Swagger / OpenAPI
• Integration tests (Testcontainers)
• Authentication & authorization
• Soft deletes
• Production profiles

---

📄 License

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