Spring Boot REST API with PostgreSQL

Educational project: REST API for managing books built with Spring Boot 4 and PostgreSQL.

What You Will Learn

• Building REST API with Spring Boot
• Working with databases using Spring Data JPA
• Data validation
• Error handling (RFC 7807 Problem Details)
• Basic Authentication
• Swagger/OpenAPI documentation
• Docker for database
• Writing tests

Requirements

Before starting, make sure you have installed:

• Java 17+ — check: java -version
• Maven 3.8+ — check: mvn -version
• Docker — check: docker --version

Quick Start (5 minutes)

Step 1: Clone the repository

git clone https://github.com/OKaluzny/spring-boot-rest-api-postgresql.git
cd spring-boot-rest-api-postgresql

Step 2: Start PostgreSQL

docker-compose up -d postgres

Verify the container is running:

docker ps

You should see container book-db with status Up.

Step 3: Run the application

mvn spring-boot:run

Wait for the message:

Started Application in X seconds

Step 4: Open Swagger UI

Open in browser: http://localhost:8080/swagger-ui.html

Here you can interactively test the API.

Step 5: Authorization

API requires authentication:

• Username: user
• Password: user

In Swagger UI click the "Authorize" button and enter these credentials.

Your First Request with curl

Create a book:

curl -X POST http://localhost:8080/api/books \
  -H "Content-Type: application/json" \
  -u user:user \
  -d '{"name": "Java Programming", "description": "Learn Java", "tags": ["java"]}'

Response:

{
  "id": 1,
  "name": "Java Programming",
  "description": "Learn Java",
  "tags": ["java"]
}

Get all books:

curl http://localhost:8080/api/books -u user:user

API Endpoints

Method	URL	Description
POST	/api/books	Create a book
GET	/api/books	Get all books (paginated)
GET	/api/books/{id}	Get book by ID
GET	/api/books?name=Java	Search by name
PUT	/api/books/{id}	Update a book
DELETE	/api/books/{id}	Delete a book

Pagination

GET /api/books?page=0&size=10&sort=name,asc

• page — page number (starting from 0)
• size — number of items per page
• sort — sorting (field,direction)

Project Structure

src/main/java/com/kaluzny/
│
├── Application.java          # Entry point
│
├── config/                   # Configuration
│   ├── SecurityConfig.java   # Security settings
│   └── OpenApiConfig.java    # Swagger settings
│
├── domain/                   # Data layer
│   ├── Book.java             # JPA entity
│   └── BookRepository.java   # Repository
│
├── dto/                      # Data Transfer Objects
│   ├── BookCreateRequest.java
│   ├── BookUpdateRequest.java
│   ├── BookResponse.java
│   └── BookMapper.java
│
├── service/                  # Business logic
│   └── BookService.java
│
├── exception/                # Error handling
│   ├── BookNotFoundException.java
│   └── GlobalExceptionHandler.java
│
└── web/                      # REST controllers
    └── BookRestController.java

Architecture

HTTP Request
     ↓
┌─────────────────┐
│   Controller    │  ← Receives DTO, validation
└────────┬────────┘
         ↓
┌─────────────────┐
│    Service      │  ← Business logic
└────────┬────────┘
         ↓
┌─────────────────┐
│   Repository    │  ← Database operations
└────────┬────────┘
         ↓
┌─────────────────┐
│   PostgreSQL    │
└─────────────────┘

Stopping the Application

1. Stop Spring Boot: Ctrl+C in terminal
2. Stop PostgreSQL:

docker-compose down

Running Tests

mvn test

Tests use H2 in-memory database, PostgreSQL is not required.

Useful Links

URL	Description
http://localhost:8080/swagger-ui.html	Swagger UI
http://localhost:8080/v3/api-docs	OpenAPI JSON
http://localhost:8080/actuator/health	Health check

Troubleshooting

Error: "Port 8080 already in use"

Find and stop the process:

lsof -i :8080
kill -9 <PID>

Error: "Connection refused" to PostgreSQL

Check that container is running:

docker ps
docker-compose up -d postgres

Error: "docker: command not found"

Install Docker Desktop: https://www.docker.com/products/docker-desktop

Technologies

Technology	Version	Description
Java	17	Programming language
Spring Boot	4.0.2	Framework
Spring Data JPA	-	ORM for database
Spring Security	-	Security
PostgreSQL	16	Database
Swagger/OpenAPI	3.1	API documentation
Lombok	1.18	Reduce boilerplate
JUnit 5	-	Testing

License

MIT