Skip to content

README.md

Latest commit

 

History

History
234 lines (180 loc) · 5.31 KB

README.md

File metadata and controls

234 lines (180 loc) · 5.31 KB

Spring Boot REST API with PostgreSQL

Build

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