Introduction The Product Distribution Dashboard API is a RESTful service built with Spring Boot that manages product distribution operations across warehouses and stores. The API provides endpoints for managing products, warehouses, stores, stock assignments, and analytics metrics.
Base URL The API base URL varies by environment:
Development : http://localhost:8080Production : Configured via SERVER_URL environment variable
All API endpoints are prefixed with /api.
Available Endpoints The API is organized into five main resource groups:
Products Method Endpoint Description GET/api/productsRetrieve all products GET/api/products/{id}Retrieve a specific product by ID
Warehouses Method Endpoint Description GET/api/warehousesRetrieve all warehouses GET/api/warehouses/{id}Retrieve a specific warehouse by ID
Stores Method Endpoint Description GET/api/storesRetrieve all stores GET/api/stores/{id}Retrieve a specific store by ID
Stock Assignments Method Endpoint Description POST/api/stock-assignments/distributeTrigger product distribution algorithm GET/api/stock-assignmentsRetrieve stock assignments with optional filters GET/api/stock-assignments/stores/{storeId}Retrieve assignments for a specific store GET/api/stock-assignments/products/{productId}Retrieve assignments for a specific product GET/api/stock-assignments/warehouses/{warehouseId}Retrieve assignments for a specific warehouse
Metrics Method Endpoint Description GET/api/metrics/globalRetrieve global distribution metrics GET/api/metrics/detailedRetrieve detailed metrics with optional filters
Common Patterns Filtering Several endpoints support query parameter filtering:
Stock Assignments Filtering The /api/stock-assignments and /api/metrics/detailed endpoints accept the following query parameters:
storeId (string): Filter by store identifierwarehouseId (string): Filter by warehouse identifierproductId (string): Filter by product identifier
Example: GET /api/stock-assignments?storeId=S001 & productId = P123
Filters use the StockAssignmentCriteria object with Jakarta validation for parameter validation.
The current API implementation does not support pagination . All list endpoints return complete datasets. For large datasets, consider:
Using specific ID-based endpoints (e.g., /api/stock-assignments/stores/{storeId})
Applying query filters to reduce result set size
Implementing client-side pagination
Pagination may be added in future API versions as data volumes grow.
Response Caching Metrics endpoints utilize Spring Cache to improve performance:
Global Metrics (/api/metrics/global): Cached resultsDetailed Metrics (/api/metrics/detailed): Cached results per filter criteria
Cache configuration is defined in application.properties with cache type simple.
All API responses use JSON format with Content-Type: application/json.
Success Responses Successful responses return appropriate HTTP status codes:
200 OK: Successful GET request201 Created: Successful POST request (distribution triggered)
Response bodies contain either:
A single DTO object for individual resource requests
An array of DTO objects for list requests
Example Product Response: { "id" : "P001" , "name" : "Product Name" , "description" : "Product description" , "price" : 29.99 }
Example List Response: [ { "id" : "P001" , "name" : "Product Name" }, { "id" : "P002" , "name" : "Another Product" } ]
Error Responses Error responses follow a standardized format using the ErrorResponseDTO structure:
{ "statusCode" : 404 , "message" : "Resource not found: Store with ID S999" , "timestamp" : "2026-03-09T14:30:00.000Z" , "path" : "/api/stores/S999" }
See the Error Handling section below for detailed information.
Error Handling The API implements comprehensive error handling through the RestExceptionHandler class using Spring’s @RestControllerAdvice.
Error Types Exception Status Code Description ResourceNotFoundException404Requested resource not found IllegalArgumentException400Invalid request parameters MethodArgumentNotValidException400Validation failure on request body/parameters DataLoadingException500Error loading data from external sources ConfigurationException500Application configuration error Generic Exception 500Unexpected server error
Validation Errors Validation errors provide detailed field-level error messages:
{ "statusCode" : 400 , "message" : "Validation failed: storeId: must not be null, productId: must match pattern [A-Z0-9]+" , "timestamp" : "2026-03-09T14:30:00.000Z" , "path" : "/api/stock-assignments" }
Error Response Structure All error responses include:
statusCode (integer): HTTP status codemessage (string): Human-readable error descriptiontimestamp (string): ISO 8601 timestamp of when the error occurredpath (string): Request URI that caused the error
CORS Configuration The API implements Cross-Origin Resource Sharing (CORS) to enable frontend applications to make requests.
CORS Settings
Allowed Origins : Configured via app.frontend.url propertyAllowed Methods : GET, POST, OPTIONSAllowed Headers : All headers (*)Exposed Headers : DefaultAllow Credentials : Not configured (defaults to false)
CORS is configured globally for all endpoints (/**) in the CorsConfig class.
The API allows only the configured frontend URL. Requests from other origins will be blocked by CORS policy.
For detailed authentication and CORS setup, see the Authentication page.
Data Models The API uses Data Transfer Objects (DTOs) for all request and response bodies. Key DTOs include:
ProductDTO : Product informationWarehouseDTO : Warehouse details including location and capacityStoreDTO : Store information with demand dataStockAssignmentDTO : Product distribution assignmentsGlobalMetricsDTO : Aggregate distribution metricsDetailedMetricsDTO : Granular metrics with breakdowns
Refer to individual endpoint documentation for detailed DTO structures.
Rate Limiting The API currently does not implement rate limiting . Consider implementing client-side throttling for high-frequency requests, especially for the /api/stock-assignments/distribute endpoint.
Versioning The API does not currently use versioning. All endpoints are considered v1 by default. Breaking changes will be communicated through:
Version headers (planned)
API changelog documentation
Deprecation notices
Next Steps
Authentication Learn about CORS configuration and security setup
Products Explore product management endpoints
Warehouses Learn about warehouse endpoints
Metrics Understand analytics and reporting APIs
