Skip to content

README.md

Latest commit

 

History

History
426 lines (347 loc) · 12.2 KB

README.md

File metadata and controls

426 lines (347 loc) · 12.2 KB

Customer management API - learning project

A comprehensive Spring Boot REST API demonstration project designed to help novice developers learn API development and OpenAPI documentation generation.

Learning objectives

This project serves as a practical learning resource for:

  • REST API Design - Modern API patterns and best practices
  • Spring Boot Development - Controller, service, and model layer architecture
  • OpenAPI 3.0 Specification - Professional API documentation generation
  • API Testing - Unit tests, integration tests, and interactive testing
  • HTTP Methods & Status Codes - Proper usage of GET, POST, PUT, PATCH, DELETE
  • Data Modeling - Entity relationships and nested objects
  • Error Handling - Custom exceptions and validation patterns

Quick start

Prerequisites

  • Java 17 or higher
  • Maven 3.6 or higher

Run the application

# Build and start the application
./mvnw spring-boot:run

# The application will start on http://localhost:8080

Access interactive documentation

API learning guide

1. CRUD operations (Create, Read, Update, Delete)

1.1 Create customer - POST /customer

Learning Focus: Request body handling, validation, nested objects

POST /customer
{
  "id": "CUST001",
  "name": "Alice Johnson",
  "address": {
    "street": "123 Main St",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "USA"
  },
  "phone": "555-0123",
  "type": "VIP"
}

Key Concepts:

  • JSON request body binding with @RequestBody
  • Nested object serialization (Address within Customer)
  • Enum validation (CustomerType: INDIVIDUAL, BUSINESS, VIP, PREMIUM)
  • Custom validation and error responses

1.2 Read customer - GET /customer/{customerID}

Learning Focus: Path variables, error handling

GET /customer/CUST001

Key Concepts:

  • Path variable binding with @PathVariable
  • Custom exception handling (CustomerNotFoundException)
  • HTTP status codes (200 OK, 404 Not Found)

1.3 Update customer - PUT /customer

Learning Focus: Full resource replacement

PUT /customer
{
  "id": "CUST001",
  "name": "Alice Johnson Updated",
  "address": { /* complete address object */ },
  "phone": "555-9999",
  "type": "PREMIUM"
}

Key Concepts:

  • PUT semantics (complete resource replacement)
  • Idempotent operations
  • Business logic validation

1.4 Partial update - PATCH /customer/{customerID}

Learning Focus: Partial updates, dynamic field handling

PATCH /customer/CUST001
{
  "name": "Updated Name Only",
  "phone": "555-8888"
}

Key Concepts:

  • PATCH semantics (partial updates)
  • Dynamic field processing with Map<String, Object>
  • Nested object partial updates
  • Field-level validation

1.5 Delete customer - DELETE /customer/{customerID}

Learning Focus: Resource deletion patterns

DELETE /customer/CUST001

Key Concepts:

  • DELETE method semantics
  • Idempotent deletion
  • Error handling for non-existent resources

2. Advanced query operations

2.1 Pagination - GET /customers

Learning Focus: Query parameters, pagination patterns

GET /customers?page=0&size=10&name=Alice&type=VIP&city=New York&state=NY

Key Concepts:

  • Query parameter binding with @RequestParam
  • Default parameter values
  • Optional parameters (required = false)
  • Pagination response wrapper (PaginatedResponse<T>)
  • Filter combinations and business logic

2.2 Advanced search - POST /customers/search

Learning Focus: Complex search criteria, request body alternatives

POST /customers/search
{
  "name": "Alice",
  "type": "VIP",
  "city": "New York",
  "state": "NY",
  "zipCode": "10001",
  "phoneAreaCode": "555",
  "minAge": 25,
  "maxAge": 65
}

Key Concepts:

  • When to use POST for search (complex criteria)
  • Search criteria objects
  • Range validation (age ranges)
  • Multiple filter combinations

2.3 Batch operations - POST /customers/batch

Learning Focus: Array processing, batch validation

POST /customers/batch
[
  {
    "id": "BATCH001",
    "name": "Batch Customer 1",
    /* ... */
  },
  {
    "id": "BATCH002",
    "name": "Batch Customer 2",
    /* ... */
  }
]

Key Concepts:

  • Array/List handling in REST APIs
  • Individual item validation within batches
  • Partial success scenarios
  • Batch size limitations

Architecture overview

Project structure

src/main/java/com/restexample/restdemo/
├── RestDemoApplication.java          # Spring Boot application entry point
├── config/
│   └── OpenApiConfig.java           # OpenAPI configuration and metadata
├── controller/
│   └── CustomerAPIService.java      # REST endpoints and request handling
├── model/
│   ├── Customer.java               # Main entity with business methods
│   ├── CustomerType.java           # Enum for customer types
│   ├── CustomerList.java           # In-memory data management
│   ├── Address.java                # Nested entity example
│   ├── CustomerSummary.java        # Lightweight response model
│   ├── CustomerSearchCriteria.java # Search request model
│   └── PaginatedResponse.java      # Generic pagination wrapper
└── exception/
    ├── CustomerNotFoundException.java    # Custom domain exception
    ├── ValidationException.java         # Input validation exception
    ├── CustomerException.java           # Exception response wrapper
    └── CustomerExceptionHandler.java    # Global exception handling

Design patterns demonstrated

1. Controller Layer Pattern

  • Single responsibility (HTTP handling only)
  • Clear endpoint organization
  • Comprehensive input validation
  • Proper HTTP status code usage

2. Model Layer Patterns

  • Entity design with business methods
  • Enum usage for type safety
  • Nested object relationships
  • Response models vs domain models

3. Exception Handling Pattern

  • Custom domain exceptions
  • Global exception handler with @ControllerAdvice
  • Consistent error response format
  • Proper HTTP status mapping

4. Data Transfer Patterns

  • Request/Response models
  • Pagination wrapper pattern
  • Search criteria pattern
  • Batch operation pattern

OpenAPI documentation features

1. API Metadata Configuration

Located in config/OpenApiConfig.java:

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
            .info(new Info()
                    .title("Customer Management API")
                    .version("1.0.0")
                    .description("Comprehensive REST API demonstration...")
                    .contact(/* contact info */)
                    .license(/* license info */))
            .servers(List.of(
                    new Server().url("http://localhost:8080").description("Development server"),
                    new Server().url("https://api.example.com").description("Production server")
            ));
}

Learning Points:

  • API versioning strategies
  • Environment-specific server configurations
  • Professional metadata for API consumers
  • Contact and licensing information

2. Controller Documentation Annotations

@Tag - Logical Grouping

@Tag(name = "Customer Management", description = "REST API for managing customer data...")
public class CustomerAPIService {

@Operation - Detailed Endpoint Documentation

@Operation(
        summary = "Create a new customer",
        description = """
            Creates a new customer with complete profile information...
            This endpoint demonstrates:
            - Nested object handling (Address within Customer)
            - Enum validation (CustomerType)
            - Input validation and error handling
            """,
        tags = {"CRUD Operations"}
)

@Parameter - Request Documentation

@Parameter(
        description = "Unique identifier of the customer",
        example = "CUST001"
)
@PathVariable String customerID

@ApiResponses - Response Documentation

@ApiResponses({
        @ApiResponse(responseCode = "200", description = "Customer created successfully"),
        @ApiResponse(responseCode = "400", description = "Invalid customer data provided")
})

3. Generated Documentation Features

The OpenAPI specification automatically generates:

  • Interactive API Testing - Try endpoints directly from Swagger UI
  • Request/Response Examples - Auto-generated from your models
  • Schema Documentation - Complete data model documentation
  • Validation Rules - Derived from your validation annotations
  • Error Response Documentation - Based on your exception handling

Testing strategy

1. Unit Tests (src/test/java/)

  • CustomerAPIServiceTest.java - Controller method testing with MockMvc
  • CustomerTypeTest.java - Enum functionality testing
  • RestDemoApplicationTests.java - Spring context loading
./mvnw test

2. Integration Tests (test-api-integration.sh)

  • Complete API workflow testing
  • Error scenario validation
  • End-to-end request/response verification
./test-api-integration.sh

3. Interactive Testing (Swagger UI)

  • Real-time API exploration
  • Parameter experimentation
  • Response inspection
  • Authentication testing (if implemented)

Learning exercises

Beginner exercises

  1. Add New Fields: Add an email field to the Customer model
  2. Extend Validation: Add email format validation
  3. New Endpoint: Create a GET /customers/count endpoint
  4. Custom Response: Create a CustomerDetails response model

Intermediate exercises

  1. Add Authentication: Implement basic API key authentication
  2. Add Logging: Add request/response logging
  3. Database Integration: Replace in-memory storage with JPA
  4. Add Caching: Implement response caching

Advanced exercises

  1. API Versioning: Implement v1 and v2 API versions
  2. Rate Limiting: Add request throttling
  3. Async Processing: Implement async batch operations
  4. Metrics Integration: Add API metrics and monitoring

Development commands

Build and run

# Clean build
./mvnw clean compile

# Run application
./mvnw spring-boot:run

# Build JAR file
./mvnw clean package

# Run built JAR
java -jar target/rest-demo-0.0.1-SNAPSHOT.jar

Testing

# Run all tests
./mvnw test

# Run specific test class
./mvnw test -Dtest=CustomerAPIServiceTest

# Run tests with coverage
./mvnw test jacoco:report

Development mode

# Auto-reload on changes
./mvnw spring-boot:run -Dspring-boot.run.jvmArguments="-Dspring.profiles.active=dev"

# Skip tests during development builds
./mvnw clean package -DskipTests

API endpoints summary

Method Endpoint Purpose Key Learning Concepts
POST /customer Create customer Request body, validation, nested objects
GET /customer/{id} Get by ID Path variables, error handling
PUT /customer Update customer Full resource replacement
PATCH /customer/{id} Partial update Dynamic field updates
DELETE /customer/{id} Delete customer Resource deletion
GET /customers List with pagination Query parameters, pagination
POST /customers/search Advanced search Complex criteria, POST for search
POST /customers/batch Batch create Array processing, partial success

Next steps

  1. Explore the Swagger UI - Start with http://localhost:8080/swagger-ui/index.html
  2. Run the Tests - Execute ./mvnw test to see comprehensive testing patterns
  3. Modify and Experiment - Try the learning exercises above
  4. Study the Code - Compare controller annotations with generated documentation
  5. Build Your Own API - Apply these patterns to your own domain model

Additional resources
⚡