apirestful/README.md

API Restful - Customer CRUD Application

A Spring Boot 4 RESTful API application that provides CRUD operations for managing customers using an H2 in-memory database.

Features

• RESTful API: Full CRUD operations for Customer management
• Async Processing: All API operations are asynchronous using @EnableAsync
• H2 Database: In-memory database for easy testing and development
• JPA Repository: Data persistence using Spring Data JPA
• DTOs: Data Transfer Objects for clean API contracts
• Validation: Input validation using Jakarta Validation
• Exception Handling: Global exception handler for consistent error responses
• Security: Spring Security configured for development (CSRF disabled, all endpoints open)
• Lombok: Reduced boilerplate code
• Swagger/OpenAPI: Interactive API documentation with SpringDoc OpenAPI 3.0

Project Structure

src/main/java/com/manalejandro/apirestful/
├── ApirestfulApplication.java       # Main application class
├── config/
│   ├── AsyncConfig.java             # Async configuration with thread pool
│   └── SecurityConfig.java          # Security configuration
├── controllers/
│   └── CustomerController.java      # REST controller for customers
├── dto/
│   ├── CustomerDTO.java             # Response DTO
│   └── CustomerRequestDTO.java      # Request DTO with validations
├── entities/
│   └── Customer.java                # JPA entity
├── exceptions/
│   ├── CustomerNotFoundException.java
│   ├── DuplicateEmailException.java
│   └── GlobalExceptionHandler.java  # Global exception handler
├── mapper/
│   └── CustomerMapper.java          # Entity-DTO mapper
├── repositories/
│   └── CustomerRepository.java      # JPA repository
└── services/
    ├── CustomerService.java         # Service interface
    └── impl/
        └── CustomerServiceImpl.java # Service implementation with async

API Endpoints

Method	Endpoint	Description
GET	/api/customers	Get all customers
GET	/api/customers/{id}	Get customer by ID
POST	/api/customers	Create a new customer
PUT	/api/customers/{id}	Update a customer
DELETE	/api/customers/{id}	Delete a customer

Customer Model

Field	Type	Description	Constraints
id	Long	Unique identifier	Auto-generated
firstName	String	Customer's first name	Required, max 100
lastName	String	Customer's last name	Required, max 100
email	String	Customer's email	Required, unique, valid email
phone	String	Customer's phone number	Optional, max 20
address	String	Customer's address	Optional, max 255
createdAt	LocalDateTime	Record creation timestamp	Auto-generated
updatedAt	LocalDateTime	Last update timestamp	Auto-generated

Request/Response Examples

Create Customer (POST /api/customers)

Request:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "address": "123 Main Street, City, Country"
}

Response (201 Created):

{
  "id": 1,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "address": "123 Main Street, City, Country",
  "createdAt": "2025-12-13T10:30:00",
  "updatedAt": "2025-12-13T10:30:00"
}

Get All Customers (GET /api/customers)

Response (200 OK):

[
  {
    "id": 1,
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": "123 Main Street, City, Country",
    "createdAt": "2025-12-13T10:30:00",
    "updatedAt": "2025-12-13T10:30:00"
  }
]

Error Response Example

Response (404 Not Found):

{
  "status": 404,
  "message": "Customer not found with id: 99",
  "timestamp": "2025-12-13T10:35:00"
}

Eclipse IDE Setup

If you're using Eclipse, you need to install the Lombok plugin to avoid IDE errors:

1. Download Lombok jar:

java -jar ~/.m2/repository/org/projectlombok/lombok/*/lombok-*.jar

2. Or download manually from projectlombok.org

3. Run the installer and select your Eclipse installation

4. Restart Eclipse

Note: The IDE errors you see are only annotation processing issues. The code compiles and runs correctly with Maven.

Running the Application

Prerequisites

• Java 21 or higher
• Maven 3.8+

Run with Maven

./mvnw spring-boot:run

The application will start at http://localhost:8080

Access H2 Console

Navigate to http://localhost:8080/h2-console with:

• JDBC URL: jdbc:h2:mem:customersdb
• Username: sa
• Password: (empty)

Access Swagger UI

Navigate to http://localhost:8080/swagger-ui.html to access the interactive API documentation.

Features:

• Interactive API testing
• Request/Response examples
• Model schemas
• Try it out functionality
• Authentication testing

OpenAPI Specification:

• JSON format: http://localhost:8080/v3/api-docs
• YAML format: http://localhost:8080/v3/api-docs.yaml

Swagger UI Preview: The Swagger UI includes:

• Customer Management tag with all CRUD operations
• Detailed parameter descriptions
• Example values for all fields
• Response codes and error messages
• Schema definitions for all DTOs

Docker

Build Docker Image

docker build -t apirestful:latest .

Run Docker Container

docker run -p 8080:8080 apirestful:latest

Using Docker Compose (optional)

docker-compose up -d

Testing the API

See TESTING.md for complete test results and validation.

Using cURL

Create a customer:

curl -X POST http://localhost:8080/api/customers \
  -H "Content-Type: application/json" \
  -d '{"firstName":"John","lastName":"Doe","email":"john@example.com","phone":"+1234567890","address":"123 Main St"}'

Get all customers:

curl http://localhost:8080/api/customers

Get customer by ID:

curl http://localhost:8080/api/customers/1

Update a customer:

curl -X PUT http://localhost:8080/api/customers/1 \
  -H "Content-Type: application/json" \
  -d '{"firstName":"Jane","lastName":"Doe","email":"jane@example.com","phone":"+0987654321","address":"456 Oak Ave"}'

Delete a customer:

curl -X DELETE http://localhost:8080/api/customers/1

Technologies Used

• Spring Boot 4.0.0
• Spring Data JPA
• Spring Data REST
• Spring Security
• SpringDoc OpenAPI 2.7.0 (Swagger UI)
• H2 Database
• Lombok
• Jakarta Validation
• Java 21

License

This project is for demonstration purposes.