Java API Server

A modern Java REST API server following best practices with Spring Boot, comprehensive testing, and code quality tools.

Features

• 🚀 RESTful API server using Spring Boot 3
• ✅ Comprehensive unit tests with JUnit 5
• 🔍 Code quality tools: Checkstyle, SpotBugs, PMD
• 📊 Code coverage reporting with JaCoCo
• 📦 Modern project structure following Java best practices
• 🔧 Makefile for common development tasks
• ⚡ Built-in validation and error handling

Project Structure

.
├── src/
│   ├── main/
│   │   ├── java/com/aaronsun/java/
│   │   │   ├── JavaApiServerApplication.java  # Application entry point
│   │   │   └── internal/
│   │   │       ├── api/                       # REST controllers
│   │   │       └── models/                    # Data models
│   │   └── resources/
│   │       └── application.properties         # Application configuration
│   └── test/
│       └── java/com/aaronsun/java/            # Test classes
├── pom.xml                                    # Maven configuration
├── checkstyle.xml                             # Checkstyle rules
├── Makefile                                   # Build automation
└── README.md                                  # This file

Prerequisites

• Java 21 or later
• Maven 3.8 or later
• Make (optional, for using Makefile)

Quick Start

Install Dependencies

make install
# or
mvn clean install -DskipTests

Run the Server

make run
# or
mvn spring-boot:run

The server will start on http://localhost:8080 by default.

Build the Application

make build
# or
mvn clean package -DskipTests

The JAR file will be created at target/java-api-server-1.0.0.jar.

Run Tests

make test
# or
mvn test

Run Tests with Coverage

make test-coverage
# or
mvn clean test jacoco:report

Coverage report will be available at target/site/jacoco/index.html.

Run Linters

All Linters

make lint

Individual Linters

make lint-checkstyle  # Run Checkstyle
make lint-spotbugs    # Run SpotBugs
make lint-pmd         # Run PMD

Or using Maven directly:

mvn checkstyle:check   # Checkstyle
mvn spotbugs:check     # SpotBugs
mvn pmd:check          # PMD

API Endpoints

Health Check

GET /health

Returns the health status of the service.

Response:

{
  "status": "ok",
  "service": "java-api-server"
}

Users API

Get All Users

GET /api/v1/users

Response:

{
  "data": [
    {
      "id": 1,
      "name": "John Doe",
      "email": "[email protected]"
    }
  ]
}

Get User by ID

GET /api/v1/users/:id

Response:

{
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]"
  }
}

Create User

POST /api/v1/users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "[email protected]"
}

Response:

{
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "[email protected]"
  }
}

Delete User

DELETE /api/v1/users/:id

Response:

{
  "message": "User deleted"
}

Environment Variables

• PORT: Server port (default: 8080)
• ENV: Environment mode (development/production, default: development)

Makefile Commands

Run make help to see all available commands:

• make build - Build the application
• make run - Run the application
• make run-jar - Build and run the application JAR
• make test - Run tests
• make test-coverage - Run tests with coverage report
• make lint - Run all linters
• make lint-checkstyle - Run Checkstyle
• make lint-spotbugs - Run SpotBugs
• make lint-pmd - Run PMD
• make clean - Clean build artifacts
• make install - Install dependencies
• make verify - Verify the project (compile, test, checkstyle, etc.)
• make ci - Run CI checks (lint + test)

Code Quality Tools

This project includes several code quality tools:

Checkstyle

Checks code style and formatting. Configuration is in checkstyle.xml.

SpotBugs

Static analysis tool to find bugs. Configured in pom.xml.

PMD

Source code analyzer that finds common programming flaws. Configured in pom.xml.

JaCoCo

Code coverage tool. Minimum coverage threshold is set to 80%.

Development

Code Style

• Follow Google Java Style Guide guidelines
• Ensure make lint passes before committing
• Write tests for new features

Testing

• All tests should be in *Test.java or *Tests.java files
• Use JUnit 5 for unit tests
• Use MockMvc for controller tests
• Aim for >80% test coverage

Building for Production

mvn clean package -DskipTests
java -jar target/java-api-server-1.0.0.jar

License

MIT