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:

{
  "data": {...},
  "status": "success",
  "code": 200
}

Error:

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

---

Auth Endpoints

Register User

POST /auth/register

Request:

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

Response:

{
  "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:

{
  "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:

{
  "user_id": 1,
  "valid": true
}

---

User Endpoints

Get Current User

GET /users/me?token=your_token

Response:

{
  "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:

{
  "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:

[
  {
    "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:

{
  "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:

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

Update Cart Item

PUT /cart/{cart_item_id}?token=your_token

Request:

{
  "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:

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

Response:

{
  "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:

{
  "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