Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed on your system:

Java 17

Required for Spring Boot 4.0.1. Verify with java -version

Maven

Build tool for dependency management. Included via Maven Wrapper (mvnw)

Database

PostgreSQL (production) or H2 (development, included by default)

Git

For cloning the repository
This guide uses H2 in-memory database for quick setup. For production deployment with PostgreSQL, see the Setup Guide.

​
Setup Instructions

1

Clone the Repository

First, clone the source code to your local machine:
git clone <repository-url>
cd ecommerce
The project structure includes:
  • src/main/java - Application source code
  • src/main/resources - Configuration files
  • pom.xml - Maven dependencies
2

Configure Application Properties

The default configuration in src/main/resources/application.properties is ready to use:
spring.application.name=ecommerce
spring.data.web.pageable.default-page-size=20
spring.data.web.pageable.max-page-size=50
To use PostgreSQL instead of H2, add these properties:
spring.datasource.url=jdbc:postgresql://localhost:5432/ecommerce
spring.datasource.username=your_username
spring.datasource.password=your_password
spring.jpa.hibernate.ddl-auto=update
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
3

Build the Application

Use Maven to download dependencies and compile the project:
./mvnw clean install
This command:
  • Downloads all required dependencies (Spring Boot, Hibernate, PostgreSQL driver, etc.)
  • Compiles Java source files
  • Runs tests
  • Packages the application as a JAR file
On Windows, use mvnw.cmd instead of ./mvnw
4

Run the Application

Start the Spring Boot application:
./mvnw spring-boot:run
You should see output indicating the application has started:
Finished Loading Users...
Preloaded products into the database.
Started EcommerceApplication in X.XXX seconds
The API server is now running at http://localhost:8080
The DatabasePreLoader component automatically creates sample data:

​
Make Your First API Request

Now that the API is running, let’s retrieve the product catalog.

​
Get All Products

curl http://localhost:8080/products

​
Response Structure

The API returns a paginated, HATEOAS-compliant response: 
{
  "_embedded": {
    "productViewList": [
      {
        "id": 1,
        "name": "Laptop",
        "description": "High performance laptop",
        "price": 1200.00,
        "stockQuantity": 50,
        "categories": [
          {
            "id": 1,
            "category": {
              "id": 1,
              "name": "Electronics"
            }
          }
        ],
        "createdAt": "2026-03-03T10:28:15.123",
        "updatedAt": "2026-03-03T10:28:15.123",
        "_links": {
          "self": {
            "href": "http://localhost:8080/products/1"
          },
          "products": {
            "href": "http://localhost:8080/products"
          }
        }
      },
      {
        "id": 2,
        "name": "Smartphone",
        "description": "Latest model smartphone",
        "price": 800.00,
        "stockQuantity": 100,
        "categories": [
          {
            "id": 2,
            "category": {
              "id": 1,
              "name": "Electronics"
            }
          }
        ],
        "createdAt": "2026-03-03T10:28:15.456",
        "updatedAt": "2026-03-03T10:28:15.456",
        "_links": {
          "self": {
            "href": "http://localhost:8080/products/2"
          },
          "products": {
            "href": "http://localhost:8080/products"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "http://localhost:8080/products?page=0&size=20"
    }
  },
  "page": {
    "size": 20,
    "totalElements": 2,
    "totalPages": 1,
    "number": 0
  }
}
HATEOAS Links: Each resource includes _links with URLs to related resources and actions.Pagination Metadata: The page object contains:
  • size: Items per page (default: 20, max: 50)
  • totalElements: Total number of products
  • totalPages: Number of pages available
  • number: Current page index (0-based)
Resource Data: Product information includes all entity fields from the ProductView class:
  • Basic info: id, name, description
  • Pricing: price field (BigDecimal for precision)
  • Inventory: stockQuantity
  • Categories: Array of associated categories
  • Timestamps: createdAt, updatedAt (ISO 8601 format)

​
Additional API Operations

​
Get a Specific Product

curl http://localhost:8080/products/1
Returns detailed information for product with ID 1.

​
Get All Categories

curl http://localhost:8080/categories
Lists all product categories in the system.

​
Get All Users

curl http://localhost:8080/users
Retrieves all registered users (returns UserView without password).

​
Pagination Parameters

Control pagination with query parameters: 
# Get page 2 with 10 items per page
curl "http://localhost:8080/products?page=1&size=10"

# Sort by name in ascending order
curl "http://localhost:8080/products?sort=name,asc"

# Combine pagination and sorting
curl "http://localhost:8080/products?page=0&size=5&sort=price,desc"
Page numbers are 0-indexed. The first page is page=0.

​
Create a New Product

Let’s add a new product to the catalog: 
curl -X POST http://localhost:8080/products \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wireless Headphones",
    "description": "Noise-cancelling Bluetooth headphones",
    "price": 299.99,
    "stockQuantity": 75,
    "category": ["Electronics", "Audio"]
  }'

​
Success Response

The API returns HTTP 201 Created with the new product: 
{
  "id": 3,
  "name": "Wireless Headphones",
  "description": "Noise-cancelling Bluetooth headphones",
  "price": 299.99,
  "stockQuantity": 75,
  "categories": [
    {
      "category": {
        "id": 1,
        "name": "Electronics"
      }
    },
    {
      "category": {
        "id": 2,
        "name": "Audio"
      }
    }
  ],
  "createdAt": "2026-03-03T12:30:00.789",
  "updatedAt": "2026-03-03T12:30:00.789",
  "_links": {
    "self": {
      "href": "http://localhost:8080/products/3"
    },
    "products": {
      "href": "http://localhost:8080/products"
    }
  }
}
Categories are created automatically if they don’t exist. The “Audio” category is created during this request since it didn’t exist before.

​
Update a Product

Modify existing product attributes using PATCH or PUT: 
curl -X PATCH http://localhost:8080/products/3 \
  -H "Content-Type: application/json" \
  -d '{
    "price": 279.99,
    "stockQuantity": 80
  }'
Only the provided fields are updated. The updatedAt timestamp is automatically refreshed.

​
Delete a Product

Remove a product from the catalog: 
curl -X DELETE http://localhost:8080/products/3
Returns HTTP 204 No Content on success.

​
Next Steps

Now that you have the API running, explore these topics:

API Reference

Complete documentation of all endpoints, request/response formats, and error codes

Authentication

Learn how to implement user authentication and secure your API requests

Shopping Cart

Manage shopping carts with automatic discount calculation

Pagination Guide

Use pagination, sorting, and filtering to efficiently query large datasets

​
Troubleshooting

Change the port in application.properties:
server.port=8081
Or set it via command line:
./mvnw spring-boot:run -Dspring-boot.run.arguments=--server.port=8081
If using PostgreSQL, verify:
  • PostgreSQL service is running
  • Database credentials in application.properties are correct
  • Database exists (create it with CREATE DATABASE ecommerce;)
For H2 issues, ensure no other application is locking the database file.
Common solutions:
  • Verify Java 17 is installed: java -version
  • Clear Maven cache: ./mvnw clean
  • Delete ~/.m2/repository if dependencies are corrupted
  • Check internet connection for dependency downloads
The DatabasePreLoader runs automatically on startup. If data isn’t present:
  • Check console logs for errors during preloading
  • Verify database schema was created (check logs for Hibernate DDL statements)
  • Try with a fresh H2 database (delete any existing database files)
For development, enable Spring Boot DevTools for automatic restarts when code changes are detected.

Build docs developers (and LLMs) love

Get started for freeTalk to us