Coffee Orders API

Overview

This project is a RESTful API for managing coffee orders, built with Spring Boot. It demonstrates a modern, layered architecture and follows best practices for API design, configuration, and testing.

Tech Stack

• Framework: Spring Boot 3.2.5
• Language: Java 21
• Build Tool: Maven
• Database: H2 (In-Memory and File-based)
• API Documentation: SpringDoc OpenAPI (Swagger UI)
• DTO Mapping: MapStruct
• Testing: JUnit 5, Mockito, Spring Test (MockMvc)
• Utilities: Lombok

Architecture

The application follows a classic layered architecture to ensure separation of concerns and maintainability:

• Controller (@RestController): Exposes the REST endpoints and handles the HTTP request/response cycle. It uses Data Transfer Objects (DTOs) to decouple the API contract from the internal domain model, ensuring that the API remains stable even if the underlying model changes.

• Service (@Service): Contains the core business logic. It orchestrates operations between the repository and the controller, and it's responsible for mapping between DTOs and JPA entities using MapStruct.

• Repository (@Repository): Manages data persistence using Spring Data JPA. It provides an abstraction layer over the database, allowing for easy data access and manipulation.

• Mapper (@Mapper): Uses MapStruct to automate the mapping between CoffeeOrder entities and their corresponding DTOs (CoffeeOrderRequestDTO and CoffeeOrderResponseDTO). This reduces boilerplate code and potential for human error.

• Global Exception Handling (@ControllerAdvice): A centralized exception handler intercepts exceptions thrown from any layer of the application. It provides consistent, user-friendly error responses with appropriate HTTP status codes.

API Documentation

API documentation is automatically generated using SpringDoc OpenAPI and is accessible via Swagger UI. Once the application is running, you can view and interact with the API at:

http://localhost:4000/swagger-ui.html

Getting Started

Prerequisites

• JDK 21 or later
• Apache Maven

Running the Application

1. Clone the repository.
2. Navigate to the project directory.
3. Run the application using the Maven wrapper:

   ./mvnw spring-boot:run

The API will be available at http://localhost:4000.

Configuration

The application uses YAML (.yml) for configuration and supports environment-specific profiles:

• dev (Default): Uses an in-memory H2 database, ideal for development and testing.
• prod: Uses a file-based H2 database for persistence across application restarts.

To run with a specific profile, use the spring.profiles.active property:

./mvnw spring-boot:run -Dspring-boot.run.profiles=prod

API Endpoints

Method	Endpoint	Description
POST	/orders	Creates a new coffee order.
GET	/orders	Retrieves a list of all coffee orders.
GET	/orders/{id}	Retrieves a specific coffee order by ID.
PUT	/orders/{id}/fulfill	Marks a specific order as fulfilled.

Error Handling

The API uses custom exceptions to handle specific error scenarios:

Exception	HTTP Status	Description
OrderNotFoundException	404 NOT FOUND	Thrown when an order with a given ID is not found.
OrderAlreadyFulfilledException	409 CONFLICT	Thrown when an attempt is made to fulfill an order that is already fulfilled.
MethodArgumentNotValidException	400 BAD REQUEST	Thrown by Spring when request body validation fails.

Testing

The project has a comprehensive test suite covering different layers of the application:

• Controller Tests (@WebMvcTest): These tests focus on the web layer, mocking the service layer to verify that the controller handles HTTP requests and responses correctly.
• Integration Tests (@SpringBootTest): These tests load the entire Spring application context and run end-to-end tests against a real H2 database to ensure all layers work together as expected.

To run the tests, use the following Maven command:

./mvnw test