needed_apis.txt

================================================================================
DJANGO BACKEND API ENDPOINTS REQUIRED FOR REACT FRONTEND
================================================================================

Based on the React frontend, here are all the Django API endpoints you need to build:

================================================================================
🔐 AUTHENTICATION APIs (4 endpoints)
================================================================================

1. REGISTER USER
   --------------
   POST /api/auth/register/
   
   Request Body:
   {
     "username": "string",
     "email": "string", 
     "password": "string",
     "full_name": "string",
     "user_age": number (optional),
     "user_gender": "Male|Female|Other|Prefer not to say"
   }
   
   Response (201 Created):
   {
     "token": "jwt_token_here",
     "user": {
       "id": 1,
       "username": "john_doe",
       "email": "john@example.com",
       "full_name": "John Doe",
       "user_age": 25,
       "user_gender": "Male",
       "created_at": "2024-01-15T10:30:00Z"
     }
   }


2. LOGIN USER
   ----------
   POST /api/auth/login/
   
   Request Body:
   {
     "email": "string",
     "password": "string"
   }
   
   Response (200 OK):
   {
     "token": "jwt_token_here",
     "user": {
       "id": 1,
       "username": "john_doe",
       "email": "john@example.com",
       "full_name": "John Doe",
       "user_age": 25,
       "user_gender": "Male",
       "created_at": "2024-01-15T10:30:00Z"
     }
   }


3. GET CURRENT USER
   ----------------
   GET /api/auth/user/
   
   Headers:
   Authorization: Bearer {token}
   
   Response (200 OK):
   {
     "id": 1,
     "username": "john_doe",
     "email": "john@example.com",
     "full_name": "John Doe",
     "user_age": 25,
     "user_gender": "Male",
     "created_at": "2024-01-15T10:30:00Z"
   }


4. UPDATE USER PROFILE
   -------------------
   PATCH /api/auth/user/
   
   Headers:
   Authorization: Bearer {token}
   
   Request Body:
   {
     "full_name": "string",
     "user_age": number,
     "user_gender": "string"
   }
   
   Response (200 OK):
   {
     "id": 1,
     "username": "john_doe",
     "email": "john@example.com",
     "full_name": "John Smith",
     "user_age": 26,
     "user_gender": "Male",
     "created_at": "2024-01-15T10:30:00Z"
   }


================================================================================
📦 PRODUCT APIs (3 endpoints)
================================================================================

5. LIST ALL PRODUCTS
   -----------------
   GET /api/products/
   
   Optional Query Parameters:
   ?min_price=10&max_price=100
   
   Response (200 OK):
   [
     {
       "id": 1,
       "product_name": "Laptop",
       "base_price": "999.99",
       "stock_quantity": 50
     },
     {
       "id": 2,
       "product_name": "Mouse",
       "base_price": "29.99",
       "stock_quantity": 200
     }
   ]


6. GET PRODUCT DETAIL
   ------------------
   GET /api/products/{id}/
   
   Response (200 OK):
   {
     "id": 1,
     "product_name": "Laptop",
     "base_price": "999.99",
     "stock_quantity": 50
   }


7. SEARCH PRODUCTS
   ---------------
   GET /api/products/search/?q={query}
   
   Example: GET /api/products/search/?q=laptop
   
   Response (200 OK):
   [
     {
       "id": 1,
       "product_name": "Laptop",
       "base_price": "999.99",
       "stock_quantity": 50
     }
   ]


================================================================================
📍 ADDRESS APIs (6 endpoints)
================================================================================

8. LIST USER ADDRESSES
   -------------------
   GET /api/addresses/
   
   Headers:
   Authorization: Bearer {token}
   
   Response (200 OK):
   [
     {
       "id": 1,
       "line1": "123 Main St",
       "line2": "Apt 4B",
       "city": "New York",
       "state": "NY",
       "country": "USA",
       "pincode": "10001",
       "is_default": true,
       "created_at": "2024-01-15T10:30:00Z"
     }
   ]


9. GET ADDRESS DETAIL
   ------------------
   GET /api/addresses/{id}/
   
   Headers:
   Authorization: Bearer {token}
   
   Response (200 OK):
   {
     "id": 1,
     "line1": "123 Main St",
     "line2": "Apt 4B",
     "city": "New York",
     "state": "NY",
     "country": "USA",
     "pincode": "10001",
     "is_default": true,
     "created_at": "2024-01-15T10:30:00Z"
   }


10. CREATE ADDRESS
    --------------
    POST /api/addresses/
    
    Headers:
    Authorization: Bearer {token}
    
    Request Body:
    {
      "line1": "string",
      "line2": "string" (optional),
      "city": "string",
      "state": "string", 
      "country": "string",
      "pincode": "string",
      "is_default": boolean
    }
    
    Response (201 Created):
    {
      "id": 2,
      "line1": "456 Oak Ave",
      "line2": "",
      "city": "Los Angeles",
      "state": "CA",
      "country": "USA",
      "pincode": "90001",
      "is_default": false,
      "created_at": "2024-01-20T14:30:00Z"
    }


11. UPDATE ADDRESS
    --------------
    PATCH /api/addresses/{id}/
    
    Headers:
    Authorization: Bearer {token}
    
    Request Body (all fields optional):
    {
      "line1": "string",
      "line2": "string",
      "city": "string",
      "state": "string",
      "country": "string",
      "pincode": "string",
      "is_default": boolean
    }
    
    Response (200 OK):
    {
      "id": 1,
      "line1": "789 Updated St",
      "line2": "Suite 100",
      "city": "Boston",
      "state": "MA",
      "country": "USA",
      "pincode": "02101",
      "is_default": true,
      "created_at": "2024-01-15T10:30:00Z"
    }


12. DELETE ADDRESS
    --------------
    DELETE /api/addresses/{id}/
    
    Headers:
    Authorization: Bearer {token}
    
    Response (204 No Content)


13. SET DEFAULT ADDRESS
    --------------------
    POST /api/addresses/{id}/set-default/
    
    Headers:
    Authorization: Bearer {token}
    
    Response (200 OK):
    {
      "id": 2,
      "line1": "456 Oak Ave",
      "line2": "",
      "city": "Los Angeles",
      "state": "CA",
      "country": "USA",
      "pincode": "90001",
      "is_default": true,
      "created_at": "2024-01-20T14:30:00Z"
    }
    
    Note: This should set is_default=False for all other user addresses


================================================================================
🛍️ ORDER APIs (3 endpoints)
================================================================================

14. LIST USER ORDERS
    ----------------
    GET /api/orders/
    
    Headers:
    Authorization: Bearer {token}
    
    Response (200 OK):
    [
      {
        "id": 1,
        "order_date": "2024-01-15T10:30:00Z",
        "payment_method": "Credit Card",
        "shipping_method": "Standard",
        "shipping_address": {
          "id": 1,
          "line1": "123 Main St",
          "line2": "Apt 4B",
          "city": "New York",
          "state": "NY",
          "country": "USA",
          "pincode": "10001"
        }
      }
    ]


15. GET ORDER DETAIL
    ----------------
    GET /api/orders/{id}/
    
    Headers:
    Authorization: Bearer {token}
    
    Response (200 OK):
    {
      "id": 1,
      "order_date": "2024-01-15T10:30:00Z",
      "payment_method": "Credit Card",
      "shipping_method": "Standard",
      "shipping_address": {
        "id": 1,
        "line1": "123 Main St",
        "line2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "country": "USA",
        "pincode": "10001"
      },
      "items": [
        {
          "id": 1,
          "product": {
            "id": 1,
            "product_name": "Laptop",
            "base_price": "999.99"
          },
          "order_quantity": 2,
          "product_price": "999.99",
          "discount_applied": "100.00",
          "return_status": "Not Returned",
          "return_date": null,
          "return_reason": "",
          "days_to_return": 0,
          "is_exchanged": false,
          "exchange_order": null
        }
      ]
    }


16. CREATE ORDER
    ------------
    POST /api/orders/
    
    Headers:
    Authorization: Bearer {token}
    
    Request Body:
    {
      "shipping_address": 1,
      "payment_method": "Credit Card",
      "shipping_method": "Standard",
      "items": [
        {
          "product": 1,
          "order_quantity": 2,
          "product_price": "999.99"
        },
        {
          "product": 2,
          "order_quantity": 1,
          "product_price": "29.99"
        }
      ]
    }
    
    Payment Method Options: "Credit Card", "Debit Card", "PayPal", "Gift Card"
    Shipping Method Options: "Standard", "Express", "Next-Day"
    
    Response (201 Created):
    {
      "id": 2,
      "order_date": "2024-01-20T15:00:00Z",
      "payment_method": "Credit Card",
      "shipping_method": "Standard",
      "shipping_address": {...},
      "items": [...]
    }


================================================================================
🔄 ORDER ITEM APIs (2 endpoints)
================================================================================

17. RETURN ITEM
    -----------
    POST /api/order-details/{id}/return/
    
    Headers:
    Authorization: Bearer {token}
    
    Request Body:
    {
      "return_reason": "Product was damaged"
    }
    
    Response (200 OK):
    {
      "id": 1,
      "product": {...},
      "order_quantity": 2,
      "product_price": "999.99",
      "discount_applied": "100.00",
      "return_status": "Returned",
      "return_date": "2024-01-25T10:00:00Z",
      "return_reason": "Product was damaged",
      "days_to_return": 5,
      "is_exchanged": false,
      "exchange_order": null
    }
    
    Note: Calculate days_to_return as the difference between return_date and order_date


18. EXCHANGE ITEM (Optional)
    -------------------------
    POST /api/order-details/{id}/exchange/
    
    Headers:
    Authorization: Bearer {token}
    
    Request Body:
    {
      "new_product": 3
    }
    
    Response (200 OK):
    {
      "id": 1,
      "product": {...},
      "order_quantity": 2,
      "product_price": "999.99",
      "discount_applied": "100.00",
      "return_status": "Returned",
      "return_date": "2024-01-25T10:00:00Z",
      "return_reason": "Exchange for different product",
      "days_to_return": 5,
      "is_exchanged": true,
      "exchange_order": 3
    }


================================================================================
📊 SUMMARY
================================================================================

Total API Endpoints Required: 18

Breakdown by Category:
- Authentication:    4 endpoints
- Products:          3 endpoints  
- Addresses:         6 endpoints
- Orders:            3 endpoints
- Order Details:     2 endpoints


================================================================================
🔧 ADDITIONAL BACKEND REQUIREMENTS
================================================================================

1. JWT AUTHENTICATION
   ------------------
   - Install: pip install djangorestframework-simplejwt
   - Configure JWT settings in settings.py
   - Create custom token obtain pairs that return user data


2. CORS CONFIGURATION
   ------------------
   - Install: pip install django-cors-headers
   - Add to INSTALLED_APPS
   - Configure CORS_ALLOWED_ORIGINS to include http://localhost:3000
   
   Example settings.py:
   CORS_ALLOWED_ORIGINS = [
       "http://localhost:3000",
   ]


3. PERMISSIONS
   -----------
   - Most endpoints require IsAuthenticated permission
   - Public endpoints: Product list, Product detail, Product search
   - Protected endpoints: All auth, address, order endpoints


4. SERIALIZERS NEEDED
   ------------------
   - UserSerializer (for registration, profile)
   - ProductSerializer
   - AddressSerializer
   - OrderSerializer (nested with shipping_address)
   - OrderDetailSerializer (nested with product)
   - CreateOrderSerializer (for handling order creation with items)


5. URL STRUCTURE
   -------------
   Configure urls.py to match these patterns:
   
   urlpatterns = [
       path('api/auth/register/', ...),
       path('api/auth/login/', ...),
       path('api/auth/user/', ...),
       path('api/products/', ...),
       path('api/products/<int:pk>/', ...),
       path('api/products/search/', ...),
       path('api/addresses/', ...),
       path('api/addresses/<int:pk>/', ...),
       path('api/addresses/<int:pk>/set-default/', ...),
       path('api/orders/', ...),
       path('api/orders/<int:pk>/', ...),
       path('api/order-details/<int:pk>/return/', ...),
       path('api/order-details/<int:pk>/exchange/', ...),
   ]


6. ERROR RESPONSES
   ---------------
   All endpoints should return consistent error formats:
   
   400 Bad Request:
   {
     "message": "Validation error",
     "errors": {
       "email": ["This field is required."]
     }
   }
   
   401 Unauthorized:
   {
     "message": "Authentication required"
   }
   
   404 Not Found:
   {
     "message": "Resource not found"
   }


================================================================================
💡 IMPLEMENTATION TIPS
================================================================================

1. Start with authentication endpoints first
2. Then implement product endpoints (simplest, no auth required)
3. Add address endpoints (introduces user-specific data)
4. Finally implement order endpoints (most complex, nested data)
5. Test each endpoint with the frontend as you build them


================================================================================
📝 TESTING THE APIs
================================================================================

Use tools like:
- Postman
- Thunder Client (VS Code extension)
- Django REST Framework browsable API
- curl commands

Example curl test:
curl -X POST http://localhost:8000/api/auth/register/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "testpass123",
    "full_name": "Test User"
  }'


================================================================================
END OF DOCUMENT
================================================================================