Download OpenAPI specification:
StockEase API provides comprehensive inventory management capabilities including product CRUD operations, JWT-based authentication, pagination, search, and stock analytics. All endpoints except login and health check require valid JWT authentication with USER or ADMIN roles.
Validates user credentials against stored user records via Spring Security. Upon successful authentication, issues a signed JWT token with embedded user role. Token can be used for subsequent API requests requiring USER or ADMIN role authorization.
| username required | string non-empty User account name (must not be blank) |
| password required | string non-empty User account password (must not be blank) |
{- "username": "admin",
- "password": "password123"
}{- "success": true,
- "message": "Login successful",
- "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsInJvbGUiOiJBRE1JTiIsImlhdCI6MTcwMDAwMDAwMH0.signature"
}Loads entire inventory without pagination. Returns all products sorted by ID. Use /api/products/paged for large datasets to prevent memory issues.
[- {
- "id": 1,
- "name": "Laptop",
- "quantity": 50,
- "price": 999.99,
- "totalValue": 49999.5
}, - {
- "id": 2,
- "name": "Mouse",
- "quantity": 200,
- "price": 25.99,
- "totalValue": 5198
}
]Creates a new product with provided name, quantity, and price. Validates all required fields and business rules:
| name required | string |
| quantity required | integer >= 0 |
| price required | number <double> >= 0.01 |
{- "name": "New Laptop",
- "quantity": 25,
- "price": 1299.99
}{- "id": 3,
- "name": "New Laptop",
- "quantity": 25,
- "price": 1299.99,
- "totalValue": 32499.75
}Returns product details if found, otherwise 404 error.
| id required | integer <int64> Example: 1 Product identifier |
{- "success": true,
- "message": "Product fetched successfully",
- "data": {
- "id": 1,
- "name": "Laptop",
- "quantity": 50,
- "price": 999.99,
- "totalValue": 49999.5
}
}Deletes a product by ID. Returns 404 if product not found. Deletion checks product existence first to avoid orphaned references.
| id required | integer <int64> Example: 1 Product identifier |
{- "success": true,
- "message": "Product with ID 1 has been successfully deleted.",
- "data": null
}Returns paginated product list with metadata. Prevents loading entire table into memory. Default page size is 10 items. Includes total count and page information for client-side pagination controls.
| page | integer >= 0 Default: 0 Example: page=0 Zero-based page number (default 0) |
| size | integer >= 1 Default: 10 Example: size=10 Items per page (default 10, must be positive) |
{- "success": true,
- "message": "Paged products fetched successfully",
- "data": {
- "content": [
- {
- "id": 1,
- "name": "Laptop",
- "quantity": 50,
- "price": 999.99,
- "totalValue": 49999.5
}, - {
- "id": 2,
- "name": "Mouse",
- "quantity": 200,
- "price": 25.99,
- "totalValue": 5198
}
], - "totalElements": 100,
- "totalPages": 10,
- "currentPage": 0,
- "pageSize": 10
}
}Case-insensitive substring search. For example, searching "apple" returns products like "Apple Juice", "APPLE", "Green Apple", etc. Returns 204 NO_CONTENT if no matches found.
| name required | string Example: name=laptop Search term (substring, case-insensitive) |
[- {
- "id": 1,
- "name": "Laptop",
- "quantity": 50,
- "price": 999.99,
- "totalValue": 49999.5
}
]Updates quantity for a specific product. Automatically recalculates total stock value. Prevents negative quantities.
| id required | integer <int64> Example: 1 Product identifier |
| quantity required | integer >= 0 New quantity (cannot be negative) |
{- "quantity": 75
}{- "success": true,
- "message": "Quantity updated successfully",
- "data": {
- "id": 1,
- "name": "Laptop",
- "quantity": 75,
- "price": 999.99,
- "totalValue": 74999.25
}
}Updates price for a specific product. Automatically recalculates total stock value. Prevents zero or negative prices.
| id required | integer <int64> Example: 1 Product identifier |
| price required | number <double> >= 0.01 New price (must be positive) |
{- "price": 1199.99
}{- "success": true,
- "message": "Price updated successfully",
- "data": {
- "id": 1,
- "name": "Laptop",
- "quantity": 50,
- "price": 1199.99,
- "totalValue": 59999.5
}
}Updates name for a specific product. Name must be non-empty. Uniqueness constraint enforced at database level.
| id required | integer <int64> Example: 1 Product identifier |
| name required | string non-empty New product name (must not be empty) |
{- "name": "High-Performance Laptop"
}{- "success": true,
- "message": "Name updated successfully",
- "data": {
- "id": 1,
- "name": "High-Performance Laptop",
- "quantity": 50,
- "price": 999.99,
- "totalValue": 49999.5
}
}Computes sum of (quantity * price) for all products. Useful for financial reporting and inventory valuation. Database-optimized aggregation query.
{- "success": true,
- "message": "Total stock value fetched successfully",
- "data": 99999.99
}Simple health check for orchestration and monitoring systems (Kubernetes, Docker, load balancers). Validates database connectivity via lightweight JDBC connection test. Returns 200 OK if database reachable; 500 error if unreachable. No authentication required. Used by: