Skip to content

README.md

Latest commit

 

History

History
480 lines (356 loc) · 11.6 KB

README.md

File metadata and controls

480 lines (356 loc) · 11.6 KB

CodeCraftHub

A simple personalized learning platform for developers to track courses they want to learn. Built with Spring Boot and designed for beginners learning REST API development.

Table of Contents

Project Overview

CodeCraftHub is a beginner-friendly REST API project that demonstrates how to build a complete CRUD (Create, Read, Update, Delete) application using Spring Boot. Instead of using a database, it stores data in a simple JSON file, making it easy to understand and debug.

Project Structure

CodeCraftHub/
├── pom.xml                              # Maven dependencies and build config
├── courses.json                         # Data storage (auto-created)
├── README.md                            # This documentation
└── src/main/java/com/codecrafthub/
    ├── CodeCraftHubApplication.java     # Application entry point
    ├── model/
    │   └── Course.java                  # Course data model
    ├── service/
    │   └── CourseService.java           # Business logic + file operations
    ├── controller/
    │   └── CourseController.java        # REST API endpoints
    └── exception/
        ├── CourseNotFoundException.java # 404 error handling
        ├── InvalidCourseException.java  # Validation error handling
        ├── FileOperationException.java  # File I/O error handling
        └── GlobalExceptionHandler.java  # Central exception handler

Features

  • Full CRUD Operations - Create, read, update, and delete courses
  • JSON File Storage - No database setup required
  • Input Validation - Validates all required fields with helpful error messages
  • Proper Error Handling - Returns appropriate HTTP status codes
  • Auto-generated Fields - IDs and timestamps are created automatically
  • Beginner-Friendly Code - Extensive comments throughout the codebase
  • RESTful Design - Follows REST API best practices

Installation

Prerequisites

Before you begin, ensure you have the following installed:

Software Version Download Link
Java JDK 17 or higher Download Java
Maven 3.6 or higher Download Maven

Verify Installation

Open a terminal and run these commands to verify your setup:

# Check Java version
java -version

# Check Maven version
mvn -version

Clone/Download the Project

# If using Git
git clone <repository-url>
cd CodeCraftHub

# Or simply navigate to the project folder
cd path/to/CodeCraftHub

Install Dependencies

# Download all required dependencies
mvn clean install

This command will:

  • Download Spring Boot and all dependencies
  • Compile the Java source code
  • Run any tests
  • Package the application

Running the Application

Start the Server

# Option 1: Using Maven (recommended for development)
mvn spring-boot:run

# Option 2: Run the JAR file directly
java -jar target/codecrafthub-1.0.0.jar

Verify It's Running

You should see output similar to:

====================================
  CodeCraftHub is running!
  API Base URL: http://localhost:8080/api/courses
====================================

Test the API

Open a new terminal and run:

curl http://localhost:8080/api/courses

You should see a JSON array of courses.

Stop the Server

Press Ctrl + C in the terminal where the server is running.

API Documentation

Base URL

http://localhost:8080/api/courses

Endpoints Overview

Method Endpoint Description Success Code
POST /api/courses Create a new course 201 Created
GET /api/courses Get all courses 200 OK
GET /api/courses/{id} Get a course by ID 200 OK
PUT /api/courses/{id} Update a course 200 OK
DELETE /api/courses/{id} Delete a course 204 No Content

Course Object

Field Type Required Description
id number Auto-generated Unique identifier (starts from 1)
name string Yes Name of the course
description string Yes What the course covers
target_date string Yes Target completion date (YYYY-MM-DD)
status string Yes Must be: "Not Started", "In Progress", or "Completed"
created_at string Auto-generated Timestamp when course was created

API Examples

1. Create a Course (POST)

Request:

curl -X POST http://localhost:8080/api/courses \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Boot Fundamentals",
    "description": "Learn to build REST APIs with Spring Boot",
    "target_date": "2026-06-30",
    "status": "Not Started"
  }'

Response (201 Created):

{
  "id": 1,
  "name": "Spring Boot Fundamentals",
  "description": "Learn to build REST APIs with Spring Boot",
  "target_date": "2026-06-30",
  "status": "Not Started",
  "created_at": "2026-05-05T10:30:00"
}

2. Get All Courses (GET)

Request:

curl http://localhost:8080/api/courses

Response (200 OK):

[
  {
    "id": 1,
    "name": "Spring Boot Fundamentals",
    "description": "Learn to build REST APIs with Spring Boot",
    "target_date": "2026-06-30",
    "status": "In Progress",
    "created_at": "2026-05-01T10:00:00"
  },
  {
    "id": 2,
    "name": "Docker for Developers",
    "description": "Containerize your applications",
    "target_date": "2026-08-01",
    "status": "Not Started",
    "created_at": "2026-05-03T14:45:00"
  }
]

3. Get a Single Course (GET)

Request:

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

Response (200 OK):

{
  "id": 1,
  "name": "Spring Boot Fundamentals",
  "description": "Learn to build REST APIs with Spring Boot",
  "target_date": "2026-06-30",
  "status": "In Progress",
  "created_at": "2026-05-01T10:00:00"
}

Response (404 Not Found) - If course doesn't exist:

{
  "timestamp": "2026-05-05T10:30:00",
  "status": 404,
  "error": "Not Found",
  "message": "Course not found with id: 99"
}

4. Update a Course (PUT)

Request:

curl -X PUT http://localhost:8080/api/courses/1 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Spring Boot Fundamentals",
    "description": "Updated: Master REST APIs with Spring Boot",
    "target_date": "2026-07-15",
    "status": "Completed"
  }'

Response (200 OK):

{
  "id": 1,
  "name": "Spring Boot Fundamentals",
  "description": "Updated: Master REST APIs with Spring Boot",
  "target_date": "2026-07-15",
  "status": "Completed",
  "created_at": "2026-05-01T10:00:00"
}

5. Delete a Course (DELETE)

Request:

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

Response: 204 No Content (empty response body)

Error Responses

Validation Error (400 Bad Request)

When required fields are missing or invalid:

{
  "timestamp": "2026-05-05T10:30:00",
  "status": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "errors": [
    "'name' is required",
    "'status' must be one of: 'Not Started', 'In Progress', or 'Completed'"
  ]
}

Not Found Error (404)

When the requested course doesn't exist:

{
  "timestamp": "2026-05-05T10:30:00",
  "status": 404,
  "error": "Not Found",
  "message": "Course not found with id: 99"
}

Server Error (500)

When something goes wrong on the server:

{
  "timestamp": "2026-05-05T10:30:00",
  "status": 500,
  "error": "Internal Server Error",
  "message": "An error occurred while saving data. Please try again."
}

Troubleshooting

Common Issues and Solutions

1. "Port 8080 is already in use"

Problem: Another application is using port 8080.

Solutions:

# Option A: Find and kill the process using port 8080
# On Windows:
netstat -ano | findstr :8080
taskkill /PID <PID_NUMBER> /F

# On Mac/Linux:
lsof -i :8080
kill -9 <PID_NUMBER>

# Option B: Change the port in application.properties
# Add this line: server.port=8081
# Then access API at http://localhost:8081/api/courses

2. "mvn: command not found"

Problem: Maven is not installed or not in your PATH.

Solutions:

3. "java: command not found" or "JAVA_HOME not set"

Problem: Java is not installed or configured properly.

Solutions:

  • Download Java 17+ from https://adoptium.net/
  • Set JAVA_HOME environment variable to your JDK installation path
  • Add %JAVA_HOME%\bin (Windows) or $JAVA_HOME/bin (Mac/Linux) to PATH

4. "Invalid date format for 'target_date'"

Problem: Date is not in the correct format.

Solution: Use YYYY-MM-DD format:

{
  "target_date": "2026-06-30"
}

5. "Invalid status value"

Problem: Status must be exactly one of the allowed values.

Solution: Use one of these exact strings (case-sensitive):

  • "Not Started"
  • "In Progress"
  • "Completed"

6. Application starts but API returns errors

Check these:

  1. Verify the URL is correct:

    http://localhost:8080/api/courses

  2. Check if courses.json exists and is valid JSON:

    • Open courses.json in the project root
    • Ensure it's valid JSON (use a JSON validator)
    • If corrupted, delete it and restart the app

  3. Check the console for error messages:

    • Look for stack traces or error logs
    • Common issues: file permissions, disk space

7. Changes to courses.json not reflected

Problem: The app caches data in memory.

Solution: Restart the application to reload data from the file.

Getting Help

If you encounter issues not covered here:

  1. Check the console output for error messages
  2. Verify your request format matches the examples above
  3. Ensure all required fields are provided
  4. Check that courses.json contains valid JSON

Quick Reference Card

+------------------+------------------------+---------------------------+
| Action           | Command                | Expected Response         |
+------------------+------------------------+---------------------------+
| Start server     | mvn spring-boot:run    | "CodeCraftHub is running" |
| List all         | GET /api/courses       | 200 + JSON array          |
| Get one          | GET /api/courses/1     | 200 + JSON object         |
| Create           | POST /api/courses      | 201 + created course      |
| Update           | PUT /api/courses/1     | 200 + updated course      |
| Delete           | DELETE /api/courses/1  | 204 (no body)             |
+------------------+------------------------+---------------------------+