API_DOCUMENTATION.md

# API Documentation

This is a **REST API** built with FastAPI. It provides endpoints for expense tracking and smart budget recommendations.

## Base URL

- **Local**: `http://localhost:8000`
- **Hugging Face**: `https://your-username-your-space.hf.space`

## Interactive Documentation

FastAPI automatically generates interactive API documentation:

- **Swagger UI**: `http://your-url/docs` - Interactive API explorer
- **ReDoc**: `http://your-url/redoc` - Alternative documentation format

## API Endpoints

### 1. Health Check

**GET** `/health`

Check if the API and database are running.

**Response:**
```json
{
  "status": "healthy",
  "database": "connected"
}
```

**Example:**
```bash
curl http://localhost:8000/health
```

---

### 2. Root Endpoint

**GET** `/`

Get API status.

**Response:**
```json
{
  "message": "Smart Budget Recommendation API",
  "status": "running"
}
```

---

### 3. Create Expense

**POST** `/expenses`

Create a new expense record.

**Request Body:**
```json
{
  "user_id": "user123",
  "amount": 3800,
  "category": "Groceries",
  "description": "Monthly groceries",
  "date": "2024-01-15T00:00:00",
  "type": "expense"
}
```

**Response:**
```json
{
  "id": "507f1f77bcf86cd799439011",
  "message": "Expense created successfully"
}
```

**Example:**
```bash
curl -X POST "http://localhost:8000/expenses" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user123",
    "amount": 3800,
    "category": "Groceries",
    "description": "Monthly groceries",
    "date": "2024-01-15T00:00:00",
    "type": "expense"
  }'
```

---

### 4. Get Expenses

**GET** `/expenses?user_id={user_id}&limit={limit}`

Get expenses for a specific user.

**Query Parameters:**
- `user_id` (required): User identifier
- `limit` (optional): Maximum number of expenses to return (default: 100)

**Response:**
```json
[
  {
    "id": "507f1f77bcf86cd799439011",
    "user_id": "user123",
    "amount": 3800,
    "category": "Groceries",
    "description": "Monthly groceries",
    "date": "2024-01-15T00:00:00",
    "type": "expense"
  }
]
```

**Example:**
```bash
curl "http://localhost:8000/expenses?user_id=user123&limit=10"
```

---

### 5. Create Budget

**POST** `/budgets`

Create a new budget.

**Request Body:**
```json
{
  "user_id": "user123",
  "category": "Groceries",
  "amount": 4000,
  "period": "monthly",
  "start_date": "2024-02-01T00:00:00",
  "end_date": "2024-02-29T00:00:00"
}
```

**Response:**
```json
{
  "id": "507f1f77bcf86cd799439012",
  "message": "Budget created successfully"
}
```

---

### 6. Get Budgets

**GET** `/budgets?user_id={user_id}`

Get budgets for a specific user.

**Query Parameters:**
- `user_id` (required): User identifier

**Response:**
```json
[
  {
    "id": "507f1f77bcf86cd799439012",
    "user_id": "user123",
    "category": "Groceries",
    "amount": 4000,
    "period": "monthly",
    "start_date": "2024-02-01T00:00:00",
    "end_date": "2024-02-29T00:00:00"
  }
]
```

---

### 7. Get Smart Budget Recommendations ⭐

**GET** `/recommendations/{user_id}?month={month}&year={year}`

Get personalized budget recommendations based on past spending behavior.

**Path Parameters:**
- `user_id` (required): User identifier

**Query Parameters:**
- `month` (optional): Target month (1-12). Defaults to next month if not provided
- `year` (optional): Target year. Defaults to next year if not provided

**Response:**
```json
[
  {
    "category": "Groceries",
    "average_expense": 3800.0,
    "recommended_budget": 4000.0,
    "reason": "Your average monthly grocery expense is Rs.3,800. We suggest setting your budget to Rs.4,000 for next month (includes a 5% buffer for variability).",
    "confidence": 0.85
  },
  {
    "category": "Transport",
    "average_expense": 2100.0,
    "recommended_budget": 2200.0,
    "reason": "Your average monthly transport expense is Rs.2,100. We suggest setting your budget to Rs.2,200 for next month (includes a 5% buffer for variability).",
    "confidence": 0.75
  }
]
```

**Example:**
```bash
# Get recommendations for next month (default)
curl "http://localhost:8000/recommendations/user123"

# Get recommendations for specific month
curl "http://localhost:8000/recommendations/user123?month=3&year=2024"
```

**How it works:**
- Analyzes expenses from the past 6 months
- Calculates average monthly spending per category
- Adds a 5-10% buffer based on spending variability
- Returns recommendations sorted by average expense (highest first)

---

### 8. Get Category Expenses

**GET** `/category-expenses/{user_id}?months={months}`

Get average expenses by category for the past N months.

**Path Parameters:**
- `user_id` (required): User identifier

**Query Parameters:**
- `months` (optional): Number of months to analyze (default: 3)

**Response:**
```json
[
  {
    "category": "Groceries",
    "average_monthly_expense": 3800.0,
    "total_expenses": 12,
    "months_analyzed": 3
  },
  {
    "category": "Transport",
    "average_monthly_expense": 2100.0,
    "total_expenses": 6,
    "months_analyzed": 3
  }
]
```

**Example:**
```bash
curl "http://localhost:8000/category-expenses/user123?months=6"
```

---

## Using the API with Python

```python
import requests

BASE_URL = "http://localhost:8000"

# Create an expense
expense = {
    "user_id": "user123",
    "amount": 3800,
    "category": "Groceries",
    "description": "Monthly groceries",
    "date": "2024-01-15T00:00:00",
    "type": "expense"
}
response = requests.post(f"{BASE_URL}/expenses", json=expense)
print(response.json())

# Get recommendations
response = requests.get(f"{BASE_URL}/recommendations/user123")
recommendations = response.json()
for rec in recommendations:
    print(f"{rec['category']}: {rec['recommended_budget']}")
    print(f"Reason: {rec['reason']}")
```

## Using the API with JavaScript/Fetch

```javascript
const BASE_URL = "http://localhost:8000";

// Create an expense
const expense = {
  user_id: "user123",
  amount: 3800,
  category: "Groceries",
  description: "Monthly groceries",
  date: "2024-01-15T00:00:00",
  type: "expense"
};

fetch(`${BASE_URL}/expenses`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(expense)
})
  .then(res => res.json())
  .then(data => console.log(data));

// Get recommendations
fetch(`${BASE_URL}/recommendations/user123`)
  .then(res => res.json())
  .then(recommendations => {
    recommendations.forEach(rec => {
      console.log(`${rec.category}: ${rec.recommended_budget}`);
      console.log(`Reason: ${rec.reason}`);
    });
  });
```

## Error Responses

The API returns standard HTTP status codes:

- `200 OK` - Request successful
- `400 Bad Request` - Invalid request data
- `422 Unprocessable Entity` - Validation error
- `500 Internal Server Error` - Server error

Error response format:
```json
{
  "detail": "Error message description"
}
```

## CORS

The API has CORS enabled, allowing requests from any origin. This makes it easy to integrate with frontend applications.