🛒 SpringBoot E-Commerce REST API

A production-grade, fully-featured E-Commerce backend REST API built with Spring Boot 4, Spring Security, and JWT authentication. This project demonstrates enterprise-level Java backend development covering user authentication, product/category management, shopping cart, order processing, and Stripe payment gateway integration — all exposed through a clean, documented API.

---

📌 Table of Contents

• Overview
• Tech Stack
• Key Features
• Architecture
• Project Structure
• API Modules
• Security & Authentication
• Database Design
• Getting Started
• Configuration
• API Documentation (Swagger)
• Dependencies
• Author

---

Overview

This is a backend-only REST API for an e-commerce platform, designed with clean architecture principles. It supports complete e-commerce workflows — from user registration and role-based access control, to browsing products, managing carts, placing orders, and processing payments via Stripe.

The project is built using the latest Spring Boot 4.0.1 with Java 21, making it one of the most up-to-date Spring Boot e-commerce implementations available.

---

Tech Stack

Layer	Technology
Language	Java 21
Framework	Spring Boot 4.0.1
REST	Spring Web MVC
Security	Spring Security + JWT (JJWT 0.13)
Persistence	Spring Data JPA + Hibernate
Database	MySQL 8+
Payment	Stripe Java SDK (v29.3)
API Docs	SpringDoc OpenAPI 3 (Swagger UI)
DTO Mapping	ModelMapper 3.0
Build Tool	Maven (Maven Wrapper included)
Boilerplate Reduction	Lombok
Validation	Spring Boot Starter Validation (Bean Validation)

---

Key Features

🔐 Authentication & Authorization

• JWT-based stateless authentication
• Role-based access control (ROLE_USER, ROLE_ADMIN)
• Secure password handling via Spring Security
• Protected endpoints with method-level security

🗂️ Category Management

• Create, update, delete product categories (Admin only)
• Paginated category listing

📦 Product Management

• Full CRUD for products (Admin)
• Product listing with pagination and sorting
• Search products by category or keyword
• Product image support

🛒 Shopping Cart

• Add/update/remove items from cart
• Per-user cart management
• Cart total calculation

📋 Order Management

• Place orders from cart
• Order history per user
• Order status tracking

💳 Payment Integration

• Stripe payment gateway integration
• Secure payment intent creation

📄 API Documentation

• Auto-generated Swagger UI via SpringDoc OpenAPI 3
• Interactive endpoint testing at /swagger-ui.html

---

Architecture

The application follows a standard layered architecture pattern:

┌──────────────────────────────────┐
│         REST Controllers         │  ← HTTP layer: request/response handling
├──────────────────────────────────┤
│         Service Layer            │  ← Business logic
├──────────────────────────────────┤
│         Repository Layer         │  ← Data access (Spring Data JPA)
├──────────────────────────────────┤
│         Entity / Model Layer     │  ← JPA Entities mapped to DB tables
├──────────────────────────────────┤
│         MySQL Database           │  ← Persistent storage
└──────────────────────────────────┘

Cross-cutting concerns:

• Spring Security — JWT filter chain applied at the servlet level
• ModelMapper — DTO ↔ Entity conversions in service layer
• Bean Validation — Request body validation in controllers
• Stripe SDK — Payment operations in service layer

---

Project Structure

springboot-ecommerce/
├── src/
│   ├── main/
│   │   ├── java/com/ecommerce/sb_ecom/
│   │   │   ├── controller/          # REST API controllers
│   │   │   ├── service/             # Business logic interfaces & implementations
│   │   │   ├── model/               # JPA Entity classes
│   │   │   ├── repository/          # Spring Data JPA repositories
│   │   │   ├── payload/             # DTOs (Request & Response objects)
│   │   │   ├── security/            # JWT utils, filters, Spring Security config
│   │   │   ├── exceptions/          # Custom exception classes & global handler
│   │   │   └── SbEcomApplication.java  # Spring Boot entry point
│   │   └── resources/
│   │       ├── application.properties   # App configuration
│   │       └── ...
│   └── test/
│       └── java/com/ecommerce/sb_ecom/  # Unit & Integration tests
├── .mvn/wrapper/                    # Maven wrapper
├── pom.xml                          # Maven build file
├── mvnw / mvnw.cmd                  # Maven wrapper scripts
└── README.md

---

API Modules

Authentication (/api/auth)

Method	Endpoint	Description	Access
POST	/api/auth/signup	Register a new user	Public
POST	/api/auth/signin	Login and receive JWT token	Public

Categories (/api)

Method	Endpoint	Description	Access
GET	/api/public/categories	Get all categories (paginated)	Public
POST	/api/admin/category	Create a new category	Admin
PUT	/api/admin/categories/{id}	Update a category	Admin
DELETE	/api/admin/categories/{id}	Delete a category	Admin

Products (/api)

Method	Endpoint	Description	Access
GET	/api/public/products	Get all products (paginated)	Public
GET	/api/public/categories/{id}/products	Get products by category	Public
GET	/api/public/products/keyword/{keyword}	Search products	Public
POST	/api/admin/categories/{id}/product	Add a product	Admin
PUT	/api/admin/products/{id}	Update product	Admin
DELETE	/api/admin/products/{id}	Delete product	Admin
PUT	/api/admin/products/{id}/image	Upload product image	Admin

Cart (/api/carts)

Method	Endpoint	Description	Access
POST	/api/carts/products/{productId}/quantity/{qty}	Add to cart	User
GET	/api/carts	Get user's cart	User
PUT	/api/carts/products/{productId}/quantity/{operation}	Update cart item	User
DELETE	/api/carts/{cartId}/product/{productId}	Remove from cart	User

Orders (/api/order)

Method	Endpoint	Description	Access
POST	/api/order/users/payments/{paymentMethod}	Place an order	User
GET	/api/admin/orders	Get all orders	Admin
GET	/api/order/users/myorders	Get current user's orders	User

Payments (/api/payment)

Method	Endpoint	Description	Access
POST	/api/payment/stripe	Create Stripe payment intent	User

Address (/api/addresses)

Method	Endpoint	Description	Access
POST	/api/addresses	Add a new address	User
GET	/api/addresses	Get all addresses	User
PUT	/api/addresses/{id}	Update address	User
DELETE	/api/addresses/{id}	Delete address	User

---

Security & Authentication

The API uses stateless JWT authentication via Spring Security.

Flow:

1. User registers via /api/auth/signup
2. User logs in via /api/auth/signin → receives a Bearer JWT token
3. Include the token in subsequent requests:

   Authorization: Bearer <your_jwt_token>
   

Roles:

• ROLE_USER — Can browse products, manage their cart, place orders
• ROLE_ADMIN — Full access including product/category management, order management

---

Database Design

The application uses MySQL with the following core entities:

Entity	Description
User	Registered user with roles
Role	User roles (ROLE_USER, ROLE_ADMIN)
Category	Product categories
Product	Product details including price and image
Cart	Per-user shopping cart
CartItem	Individual items in a cart
Order	Placed orders linked to user
OrderItem	Products within an order
Payment	Payment method and status
Address	Shipping/billing addresses

Schema is managed automatically by Hibernate DDL auto-configuration.

---

Getting Started

Prerequisites

Requirement	Version
Java JDK	21+
Maven	3.9+ (or use included mvnw)
MySQL Server	8.0+
Stripe Account	For payment features

1. Clone the Repository

git clone https://github.com/shivanshpal31/springboot-ecommerce.git
cd springboot-ecommerce

2. Set Up MySQL Database

CREATE DATABASE sb_ecom;

3. Configure Application Properties

Edit src/main/resources/application.properties:

# Database
spring.datasource.url=jdbc:mysql://localhost:3306/sb_ecom
spring.datasource.username=your_mysql_username
spring.datasource.password=your_mysql_password

# JPA
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

# JWT
app.jwtSecret=your_jwt_secret_key
app.jwtExpirationMs=86400000

# Stripe
stripe.secret.key=your_stripe_secret_key

4. Build and Run

# Using Maven wrapper
./mvnw spring-boot:run

# Or build JAR and run
./mvnw clean package
java -jar target/sb-ecom-0.0.1-SNAPSHOT.jar

The application starts on http://localhost:8080

---

Configuration

Property	Description	Default
server.port	Server port	8080
spring.datasource.url	MySQL JDBC URL	—
spring.jpa.hibernate.ddl-auto	Schema management	update
app.jwtSecret	JWT signing secret	—
app.jwtExpirationMs	JWT expiry in ms	86400000 (24h)
stripe.secret.key	Stripe API secret key	—

---

API Documentation (Swagger)

Once the application is running, the interactive Swagger UI is available at:

http://shivanshpal.com/swagger-ui/index.html

The OpenAPI JSON spec is available at:

http://shivanshpal.com/v3/api-docs

---

Dependencies

<!-- Core Framework -->
Spring Boot 4.0.1 (spring-boot-starter-webmvc)
Spring Data JPA         (spring-boot-starter-data-jpa)

<!-- Security -->
Spring Security         (spring-boot-starter-security)
JJWT API/Impl/Jackson  (io.jsonwebtoken 0.13.0)

<!-- Database -->
MySQL Connector/J       (com.mysql:mysql-connector-j)

<!-- Payment -->
Stripe Java SDK         (com.stripe:stripe-java 29.3.0)

<!-- API Documentation -->
SpringDoc OpenAPI 3     (springdoc-openapi-starter-webmvc-ui 3.0.0)

<!-- Utilities -->
Lombok                  (org.projectlombok:lombok)
ModelMapper             (org.modelmapper:modelmapper 3.0.0)
Spring Validation       (spring-boot-starter-validation)

<!-- Testing -->
Spring Boot Test        (spring-boot-starter-test)
Spring Security Test    (spring-security-test)

---

Author

Shivansh Pal

• GitHub: @shivanshpal31
• Repository: springboot-ecommerce

---

Note: This project is backend-only. A compatible frontend (React, Angular, etc.) can be connected by pointing it to http://shivanshpal.com/api.