Skip to main content

​
Prerequisites

Before you begin, make sure you have the following installed:
  • Docker (version 20.10 or higher)
  • Docker Compose (version 2.0 or higher)
  • Git (for cloning the repository)
Alternatively, if running without Docker:
  • Java 21 or higher
  • Maven 3.8+
  • PostgreSQL 14+
The easiest way to get started is using Docker Compose, which handles all dependencies automatically.

​
Quick Start with Docker

1

Clone the Repository

Clone the Furniture API repository to your local machine:
git clone <repository-url>
cd furniture-api
2

Start the Application

Launch the API and all dependencies using Docker Compose:
docker compose up
This command will:
  • Build the Furniture API Docker image
  • Start the PostgreSQL database
  • Initialize the database schema
  • Launch the API service on port 8082
The first run may take a few minutes as Docker downloads images and builds the application.
3

Verify the API is Running

Once the containers are up, verify the API is running:
curl http://localhost:8082/actuator/health
You should see a response like:
{
  "status": "UP"
}
4

Access Swagger UI

Open your browser and navigate to the interactive API documentation:
http://localhost:8082/doc/swagger-ui.html
The Swagger UI provides:
  • Complete API documentation
  • Interactive endpoint testing
  • Request/response examples
  • Schema definitions

​
Alternative: Running with Maven

If you prefer to run the application without Docker:
1

Configure Database

Ensure PostgreSQL is running and create a database. Update the src/main/resources/application.properties file with your database credentials:
spring.datasource.url=jdbc:postgresql://localhost:5432/furniture_db
spring.datasource.username=your_username
spring.datasource.password=your_password
2

Build and Run

Build and start the application using Maven:
./mvnw clean install
./mvnw spring-boot:run
The API will start on port 8082.

​
Making Your First API Request

Let’s create a product category and then add a product: 
# Create a category
curl -X POST http://localhost:8082/api/v1/categories \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Living Room",
    "description": "Furniture for living spaces",
    "is_active": true
  }'

# Create a product
curl -X POST http://localhost:8082/api/v1/products \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Modern Sofa",
    "description": "Comfortable 3-seater sofa with fabric upholstery",
    "sku": "SOFA-001",
    "category_id": 1,
    "price": 899.99,
    "cost_price": 450.00,
    "weight_kg": 85.5,
    "is_active": true
  }'

# Get all products
curl http://localhost:8082/api/v1/products

​
Understanding the Response

When you create a product, the API returns a ProductResponse object: 
{
  "id": 1,
  "name": "Modern Sofa",
  "description": "Comfortable 3-seater sofa with fabric upholstery",
  "sku": "SOFA-001",
  "category_id": 1,
  "price": 899.99,
  "cost_price": 450.00,
  "weight_kg": 85.5,
  "is_active": true,
  "created_at": "2026-03-03T10:30:00",
  "product_dimension_id": null,
  "product_inventory_id": null,
  "image_ids": []
}
All property names use snake_case formatting in JSON responses, as configured in the application properties.

​
Common Operations

​
Search Products

curl http://localhost:8082/api/v1/products/search/sku/SOFA-001

​
Manage Inventory

curl http://localhost:8082/api/v1/inventory/low-stock

​
Configuration

The API is configured via application.properties. Key settings: 
# Server Configuration
spring.application.name=microservice-rest
server.port=8082

# Swagger UI
springdoc.swagger-ui.path=/doc/swagger-ui.html

# JSON Response Format
spring.jackson.property-naming-strategy=SNAKE_CASE

​
Stopping the Application

To stop the Docker containers: 
docker compose down
To also remove volumes (including database data): 
docker compose down -v

​
Health Checks

The API includes Spring Boot Actuator endpoints for monitoring: 
# Health check
curl http://localhost:8082/actuator/health

# Application info
curl http://localhost:8082/actuator/info

​
Next Steps

API Reference

Explore all available endpoints in detail

Product Management

Learn about product CRUD operations

Inventory Management

Manage stock levels and inventory

Data Model

Understand the database schema and relationships
Having trouble? Check out the Swagger UI at http://localhost:8082/doc/swagger-ui.html for interactive API testing.

Build docs developers (and LLMs) love

Get started for freeTalk to us