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:

{
  "status": "healthy",
  "database": "connected"
}

Example:

curl http://localhost:8000/health

---

2. Root Endpoint

GET /

Get API status.

Response:

{
  "message": "Smart Budget Recommendation API",
  "status": "running"
}

---

3. Create Expense

POST /expenses

Create a new expense record.

Request Body:

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

Response:

{
  "id": "507f1f77bcf86cd799439011",
  "message": "Expense created successfully"
}

Example:

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:

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

Example:

curl "http://localhost:8000/expenses?user_id=user123&limit=10"

---

5. Create Budget

POST /budgets

Create a new budget.

Request Body:

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

Response:

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

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

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

# 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:

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

curl "http://localhost:8000/category-expenses/user123?months=6"

---

Using the API with 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

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:

{
  "detail": "Error message description"
}

CORS

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