brand-master/API_DOCUMENTATION.md

# API Documentation

## Base URL
```
http://localhost:8000/api
```

## Authentication

Most endpoints require JWT token. Include token as query parameter:
```
?token=your_jwt_token
```

## Response Format

All responses follow this format:

**Success:**
```json
{
  "data": {...},
  "status": "success",
  "code": 200
}
```

**Error:**
```json
{
  "detail": "Error message",
  "status": "error",
  "code": 400
}
```

---

## Auth Endpoints

### Register User
**POST** `/auth/register`

Request:
```json
{
  "email": "user@example.com",
  "password": "password123",
  "full_name": "John Doe"
}
```

Response:
```json
{
  "id": 1,
  "email": "user@example.com",
  "full_name": "John Doe",
  "created_at": "2024-04-19T10:00:00"
}
```

### Login
**POST** `/auth/login?email=user@example.com&password=password123`

Response:
```json
{
  "access_token": "eyJhbGc...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "full_name": "John Doe"
  }
}
```

### Verify Token
**POST** `/auth/verify-token?token=your_token`

Response:
```json
{
  "user_id": 1,
  "valid": true
}
```

---

## User Endpoints

### Get Current User
**GET** `/users/me?token=your_token`

Response:
```json
{
  "id": 1,
  "email": "user@example.com",
  "full_name": "John Doe",
  "phone": "+1234567890",
  "address": "123 Main St",
  "city": "New York",
  "postal_code": "10001",
  "country": "USA"
}
```

### Update Profile
**PUT** `/users/me?token=your_token`

Request:
```json
{
  "full_name": "Updated Name",
  "phone": "+0987654321",
  "address": "456 Oak Ave",
  "city": "Los Angeles"
}
```

---

## Product Endpoints

### List Products
**GET** `/products?limit=20&skip=0`

Query Parameters:
- `limit` - Results per page (default: 20)
- `skip` - Pagination offset (default: 0)
- `category_id` - Filter by category
- `gender` - Filter by gender (men/women)
- `on_sale` - Filter on sale items (true/false)
- `featured` - Filter featured items (true/false)

Response:
```json
[
  {
    "id": 1,
    "name": "Premium Running Shoes",
    "description": "High-performance running shoes",
    "price": 129.99,
    "discount_price": 89.99,
    "category_id": 1,
    "gender": "men",
    "brand": "Nike",
    "sizes": ["6", "7", "8", "9", "10"],
    "colors": ["Black", "White", "Blue"],
    "stock": 50,
    "images": ["url1", "url2"],
    "is_featured": true,
    "is_on_sale": true,
    "created_at": "2024-04-19T10:00:00"
  }
]
```

### Get Product Details
**GET** `/products/{product_id}`

### Search Products
**GET** `/products/search?q=shoes&limit=10`

### Create Product (Admin)
**POST** `/products`

Request:
```json
{
  "name": "New Shoe",
  "description": "Description",
  "price": 99.99,
  "discount_price": null,
  "category_id": 1,
  "gender": "men",
  "brand": "Brand",
  "sizes": ["8", "9", "10"],
  "colors": ["Black", "White"],
  "stock": 50,
  "images": ["url1"],
  "is_featured": false,
  "is_on_sale": false
}
```

### Update Product (Admin)
**PUT** `/products/{product_id}`

### Delete Product (Admin)
**DELETE** `/products/{product_id}`

---

## Category Endpoints

### List Categories
**GET** `/categories`

### Get Category
**GET** `/categories/{category_id}`

### Create Category (Admin)
**POST** `/categories`

### Update Category (Admin)
**PUT** `/categories/{category_id}`

### Delete Category (Admin)
**DELETE** `/categories/{category_id}`

---

## Cart Endpoints

### Get Cart
**GET** `/cart?token=your_token`

### Add to Cart
**POST** `/cart/add?token=your_token`

Request:
```json
{
  "product_id": 1,
  "quantity": 1,
  "size": "10",
  "color": "Black"
}
```

### Update Cart Item
**PUT** `/cart/{cart_item_id}?token=your_token`

Request:
```json
{
  "quantity": 2
}
```

### Remove from Cart
**DELETE** `/cart/{cart_item_id}?token=your_token`

### Clear Cart
**DELETE** `/cart?token=your_token`

---

## Order Endpoints

### Create Order
**POST** `/orders?token=your_token`

Request:
```json
{
  "shipping_address": "123 Main St",
  "shipping_city": "New York",
  "shipping_postal_code": "10001",
  "shipping_country": "USA"
}
```

Response:
```json
{
  "id": 1,
  "order_number": "ORD-20240419100000-ABC123",
  "status": "pending",
  "total_amount": 199.99,
  "items": [...]
}
```

### Get User Orders
**GET** `/orders/user/orders?token=your_token`

### Get Order Details
**GET** `/orders/{order_id}?token=your_token`

---

## Wishlist Endpoints

### Get Wishlist
**GET** `/wishlist?token=your_token`

### Add to Wishlist
**POST** `/wishlist/{product_id}?token=your_token`

### Remove from Wishlist
**DELETE** `/wishlist/{product_id}?token=your_token`

---

## Contact Endpoint

### Send Contact Message
**POST** `/contact`

Request:
```json
{
  "name": "John Doe",
  "email": "john@example.com",
  "subject": "Question about products",
  "message": "I have a question..."
}
```

---

## Error Codes

- `200` - Success
- `201` - Created
- `400` - Bad Request
- `401` - Unauthorized
- `403` - Forbidden
- `404` - Not Found
- `422` - Validation Error
- `500` - Server Error

## Rate Limiting

Currently no rate limiting. Consider implementing in production.

## CORS

CORS is enabled for:
- http://localhost:5173
- http://localhost:3000
- Configuration in `config.py`