API Version: v1.0.0

🪑 Furniture API

A robust REST API for managing a furniture catalog with advanced features including AI-generated content, real-time stock management, and dynamic pricing.

Table of Contents

Overview

The Furniture API provides a comprehensive solution for managing an online furniture catalog. Key features include:

API Showcase

Want to see what you can build with this API? Check out our demo e-commerce site:

furniture-api-showcase.vercel.app

The showcase demonstrates:

The source code for the showcase is available in our GitHub repository, demonstrating best practices for:

Use this showcase as a reference for implementing your own frontend using the Furniture API.

Getting Started

Base URL

https://furniture-api.fly.dev

Rate Limits

API Endpoints

Product Listing

GET /v1/products

Retrieve a paginated list of products with comprehensive filtering options.

Query Parameters

Parameter Type Default Description
limit number 10 Items per page (1-100)
offset number 0 Pagination offset
sort string 'newest' Sorting method
name string - Search in names/categories
category string - Product category filter
wood_type string - Wood type filter
finish string - Finish type filter
min_price number - Minimum price filter
max_price number - Maximum price filter
min_stock number - Minimum stock filter
max_stock number - Maximum stock filter
featured boolean - Featured products filter

Valid Values

sort: ['price_asc', 'price_desc', 'name_asc', 'name_desc', 'newest', 'oldest'];
category: [
  'sofa',
  'chair',
  'stool',
  'table',
  'desk',
  'kitchen',
  'vanitory',
  'matress',
  'mirror',
  'wardrove',
  'lamp',
  'tv table',
  'garden',
];
wood_type: [
  'walnut',
  'maple',
  'oak',
  'pine',
  'eucalyptus',
  'bamboo',
  'teak',
  'cedar',
];
finish: ['dark', 'medium', 'light', 'natural'];

Response Example

{
  "success": true,
  "count": 100,
  "data": [
    {
      "id": "uuid",
      "name": "Modern Oak Chair",
      "category": "chair",
      "description": "Comfortable modern chair...",
      "wood_type": "oak",
      "finish": "natural",
      "dimensions": {
        "width": 60,
        "height": 90,
        "depth": 55
      },
      "price": 299.99,
      "discount_price": 249.99,
      "weight": 12,
      "image_path": "https://...",
      "stock": 50,
      "sku": "uuid",
      "status": "active",
      "featured": true,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Product Details

GET /v1/products/:sku

Retrieve detailed information about a specific product.

Path Parameters

Response Example

{
  "success": true,
  "data": {
    // Same structure as individual product in listing
  }
}

Stock Management

PATCH /v1/products/stock

Update stock levels for multiple products in a single request.

Request Body

{
  "updates": [
    {
      "productSku": "uuid",
      "quantity": 5 // Positive for addition, negative for subtraction
    }
  ]
}

Response Example

{
  "message": "Stock updated successfully",
  "results": [
    {
      "sku": "uuid",
      "success": true,
      "newStock": 55
    }
  ]
}

Featured Products

PATCH /v1/products/:sku/featured

Toggle a product's featured status.

Path Parameters

Response Example

{
  "success": true,
  "data": {
    // Updated product details
  }
}

Product Discounts

PATCH /v1/products/:sku/discount

Apply a discount to a product.

Query Parameters

Note: Provide either discountPercentage or discountPrice, not both.

Response Example

{
  "success": true,
  "data": {
    // Updated product details with new pricing
  }
}

Data Models

Product Schema

interface Product {
  id: string;
  name: string;
  category: string;
  description: string;
  wood_type: string;
  finish: string;
  dimensions: {
    depth: number;
    width: number;
    height: number;
  };
  price: number;
  weight: number;
  image_path: string;
  stock: number;
  sku: string;
  status: 'active' | 'inactive';
  created_at: string;
  updated_at: string;
  featured: boolean;
  discount_price?: number;
  tags?: string[] | null;
}

Feature Details

AI Integration

Automated Tasks

Security Features

Error Handling

Common Error Codes

Error Response Format

{
  "success": false,
  "error": "Error message",
  "details": "Detailed error information"
}

Development

Prerequisites

Setup

  1. Clone the repository:
git clone https://github.com/your-username/furniture-api.git
cd furniture-api
  1. Install dependencies:
npm install
  1. Create .env file:
PUBLIC_ANON_KEY=your-supabase-key
GETIMG_API_KEY=your-getimg-key
PORT=3000
  1. Start development server:
npm run dev

Testing

npm run test        # Run tests
npm run test:watch  # Watch mode

Deployment

Fly.io Deployment

  1. Install Fly CLI
  2. Initialize Fly app:
fly launch
  1. Deploy:
fly deploy

Environment Variables

Set these in your deployment environment:

fly secrets set PUBLIC_ANON_KEY=your-key
fly secrets set GETIMG_API_KEY=your-key

Examples

Complex Filtering Example

# Get all oak chairs under $500, sorted by price
curl "https://furniture-api.fly.dev/v1/products?category=chair&wood_type=oak&max_price=500&sort=price_asc"

Bulk Stock Update

curl -X PATCH "https://furniture-api.fly.dev/v1/products/stock" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {"productSku": "uuid1", "quantity": 5},
      {"productSku": "uuid2", "quantity": -3}
    ]
  }'

Apply Percentage Discount

curl -X PATCH "https://furniture-api.fly.dev/v1/products/uuid/discount?discountPercentage=20"

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support open an issue on GitHub.

Last updated: November 17, 2024