E-Commerce REST API — Detailed Spring Boot Feature Specification
1. Overview
This specification defines how to implement each module of the E-commerce
REST API in Spring Boot.
Each section includes the CRUD operations, DTO structures, and endpoint
behavior required for a complete RESTful backend.
2. User Authentication & Management
2.1 Create New User (Register)
Endpoint: POST /api/users/register
Description: Allows new customers to create an account.
Request Body (UserRegistrationDTO):
"name": "John Doe",
"email": "john@[Link]",
"password": "P@ssw0rd!"
Controller Action:
Validate the email and password.
Hash the password before saving.
Save using UserRepository.
Return a success message with user info (excluding password).
2.2 Authenticate User (Login)
Endpoint: POST /api/users/login
Description: Authenticates an existing user and issues a JWT token.
Request Body:
{
"email": "john@[Link]",
"password": "P@ssw0rd!"
Controller Action:
Verify credentials using [Link]().
Compare password using a password encoder.
Generate JWT on success.
Return token and user details.
2.3 View / Update Profile
Endpoints:
GET /api/users/profile — View profile
PUT /api/users/profile — Update profile
Description: Allows an authenticated user to retrieve and update their
personal details.
Request Body (UpdateUserDTO):
"name": "John Doe",
"address": "123 Street, Harare",
"phoneNumber": "+263771234567"
Controller Action:
Use @AuthenticationPrincipal to identify the logged-in user.
Update allowed fields only (not password unless in a separate
endpoint).
Return updated profile details.
2.4 Admin — View All Users
Endpoint: GET /api/admin/users
Description: Lists all registered users.
Access: Administrator only.
Controller Action:
Use [Link]()
Return list of UserDTO objects.
3. Product Catalog Management
3.1 View All Products
Endpoint: GET /api/products
Description: Returns a paginated list of available products.
Accessible by: All users (no authentication required).
Controller Action:
Use [Link](Pageable pageable).
Return List<ProductDTO> with pagination metadata.
3.2 View Single Product
Endpoint: GET /api/products/{id}
Description: Returns full details of a single product.
Accessible by: All users.
Controller Action:
Fetch product by ID via [Link](id).
Return 404 if not found.
3.3 Search / Filter Products
Endpoint: GET /api/products/search?name={name}&category={category}
Description: Enables users to search or filter products by name or category.
Controller Action:
Implement findByNameContaining and findByCategoryId in
ProductRepository.
Combine filters dynamically.
3.4 Admin — Create a New Product
Endpoint: POST /api/admin/products
Description: Allows an admin to add a new product to the catalog.
Request Body (ProductDTO):
"name": "Wireless Mouse",
"description": "Bluetooth-enabled ergonomic mouse",
"price": 25.50,
"stockQuantity": 100,
"categoryId": 3
Controller Action:
Validate all required fields.
Map DTO → Entity using ProductMapper.
Save via [Link]().
Return created product with generated ID.
3.5 Admin — Update Product
Endpoint: PUT /api/admin/products/{id}
Description: Updates details of an existing product.
Request Body:
"name": "Wireless Mouse Pro",
"description": "Updated ergonomic mouse with USB-C",
"price": 29.99,
"stockQuantity": 200
Controller Action:
Check if product exists.
Update fields selectively.
Save and return updated entity.
3.6 Admin — Delete Product
Endpoint: DELETE /api/admin/products/{id}
Description: Removes a product from the catalog.
Controller Action:
Validate existence of product.
Call [Link](id).
Return 204 No Content.
4. Shopping Cart Management
4.1 Add Product to Cart
Endpoint: POST /api/cart
Description: Adds a product and quantity to the authenticated user’s
shopping cart.
Request Body (CartItemDTO):
"productId": 5,
"quantity": 2
Controller Action:
Validate product availability.
Add or update cart entry in CartRepository.
Return updated cart summary.
4.2 View Shopping Cart
Endpoint: GET /api/cart
Description: Retrieves the current user’s cart contents.
Controller Action:
Retrieve all cart items for the authenticated user.
Return a list of products, quantities, and total cost.
4.3 Update Cart Item Quantity
Endpoint: PUT /api/cart/{productId}
Description: Updates the quantity of a product already in the cart.
Request Body:
"quantity": 3
Controller Action:
Update the cart item’s quantity.
Recalculate subtotal and total.
4.4 Remove Product from Cart
Endpoint: DELETE /api/cart/{productId}
Description: Removes a product from the shopping cart.
Controller Action:
Delete item from cart repository for the authenticated user.
Return updated cart summary.
4.5 Clear Cart (After Order)
Triggered by: Successful order placement
Action: [Link](userId)
5. Order Management
5.1 Place Order
Endpoint: POST /api/orders
Description: Converts the current shopping cart into an order.
Controller Action:
Validate that the cart is not empty.
Create a new Order entity with order items from the cart.
Set status to "Pending".
Save using OrderRepository.
Clear the cart afterward.
5.2 View Order History
Endpoint: GET /api/orders
Description: Retrieves all orders made by the authenticated customer.
Controller Action:
Fetch all orders by userId.
Return a list of OrderDTO objects.
5.3 Admin — View All Orders
Endpoint: GET /api/admin/orders
Description: Lists all customer orders for administrative oversight.
Controller Action:
Use [Link]() sorted by date.
Return order details with customer info.
5.4 Admin — Update Order Status
Endpoint: PUT /api/admin/orders/{id}/status
Description: Updates an order’s status (e.g., Pending → Shipped →
Delivered).
Request Body:
"status": "Shipped"
Controller Action:
Validate the status value.
Update and save via orderRepository.
Return updated order.
6. Entities and Repositories Overview
Entity Repository Description
Manages user persistence and queries
User UserRepository
(findByEmail, findAllCustomers).
ProductRepositor
Product Manages CRUD operations on product catalog.
y
CartIte
CartRepository Manages items per user’s cart.
m
Handles order creation, status updates, and
Order OrderRepository
lookups.
Categor CategoryReposit
(Optional) For organizing products by type.
y ory
7. DTOs and Mappers
DTO Fields Mapper Purpose
Converts User entity for
UserDTO id, name, email, role
responses.
ProductDT id, name, description, price, Handles input/output for
O stockQuantity, categoryId products.
CartItemDT
productId, quantity For cart operations.
O
id, totalAmount, orderDate, status,
OrderDTO For order summaries.
items
Each entity will have a corresponding Mapper class to convert between DTO
and entity.
the Spring Boot folder structure and class file layout will include
(entities, repositories, controllers, services, dtos, mappers)
