A comprehensive Symfony-based REST API for managing personal finances, including transactions, categories, budgets, and financial reports.
- Features
- API Endpoints
- Authentication
- Filtering & Pagination
- Budget Alerts
- Reports
- Admin Features
- Development Progress
- Future Improvements
- User registration with email and password
- JWT authentication with access and refresh tokens
- Role-based access control (User / Admin)
- System categories available to all users (Food, Transport, Bills, Entertainment, Shopping, Health, Other)
- Personal categories created by individual users
- Categories with custom icons and colors
- Owner-based access control
- Create income and expense transactions
- Assign transactions to categories
- Add descriptions and custom dates
- Filter transactions by type, categories, and date range
- Full CRUD operations with ownership validation
- Set monthly spending limits
- Category-specific budgets or total monthly budgets
- Unique constraint: one budget per user per category per month
- Automatic budget tracking
- Warning notification at 80% budget usage
- Alert notification at 100% budget usage
- Automatic check after each expense creation
- Monthly spending summaries
- Weekly spending breakdowns
- Category-wise expense distribution
- Daily spending averages
- Income vs expense totals
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/register |
Register a new user account |
| POST | /api/login |
Authenticate and receive JWT tokens |
| POST | /api/token/refresh |
Refresh expired access token |
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/categories |
List all categories (system + personal) |
| POST | /api/categories |
Create a new personal category |
| GET | /api/categories/{id} |
Get single category details |
| PUT | /api/categories/{id} |
Update a category |
| DELETE | /api/categories/{id} |
Delete a personal category |
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/transactions |
List transactions with filters and pagination |
| POST | /api/transactions |
Create a new transaction |
| GET | /api/transactions/{id} |
Get single transaction details |
| PUT | /api/transactions/{id} |
Update a transaction |
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/budgets |
List all user budgets |
| POST | /api/budgets |
Create a new budget |
| GET | /api/budgets/{id} |
Get single budget details |
| PUT | /api/budgets/{id} |
Update budget limit |
| GET | /api/budgets/status |
Get current budget usage status |
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/reports/monthly |
Get monthly spending report |
| GET | /api/reports/weekly |
Get weekly spending report |
| GET | /api/reports/budget-status |
Get all budgets with current usage |
| GET | /api/reports/category-breakdown |
Get expenses grouped by category |
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/admin/users |
List all users |
| GET | /api/admin/users/{id}/transactions |
View any user's transactions |
| POST | /api/admin/categories |
Create system category |
| PUT | /api/admin/categories/{id} |
Edit system category |
| DELETE | /api/admin/categories/{id} |
Delete system category |
All endpoints except /api/register and /api/login require a valid JWT token.
Include the token in the Authorization header:
Authorization: Bearer <your_jwt_token>
Tokens expire after a configured time. Use the refresh token endpoint to obtain a new access token without re-authenticating.
| Parameter | Type | Description | Example |
|---|---|---|---|
type |
string | Filter by transaction type | ?type=income or ?type=expense |
categories[] |
array | Filter by category IDs | ?categories[]=1&categories[]=2 |
date_from |
string | Start date (Y-m-d format) | ?date_from=2024-01-01 |
date_to |
string | End date (Y-m-d format) | ?date_to=2024-12-31 |
| Parameter | Type | Default | Description |
|---|---|---|---|
page |
int | 1 | Page number |
limit |
int | 20 | Items per page (max 100) |
{
"data": [
{ "id": 1, "amount": 50.00, "type": "expense", ... },
{ "id": 2, "amount": 100.00, "type": "income", ... }
],
"meta": {
"total": 150,
"page": 1,
"per_page": 20,
"total_pages": 8
}
}You can combine any filters together:
- All income transactions:
?type=income - Expenses in specific categories:
?type=expense&categories[]=1&categories[]=3 - All transactions in date range:
?date_from=2024-01-01&date_to=2024-01-31 - Income from specific category with pagination:
?type=income&categories[]=2&page=2&limit=10
The system automatically monitors budget usage and provides alerts:
- Triggered when spending reaches 80% of the budget limit
- Notification logged for user awareness
- Spending still allowed
- Triggered when spending reaches or exceeds the budget limit
- Strong notification logged
- User informed they have exceeded their budget
{
"category": "Food",
"limit": 500.00,
"spent": 425.00,
"remaining": 75.00,
"percentage": 85,
"status": "warning"
}- Total income for the month
- Total expenses for the month
- Net balance (income - expenses)
- Breakdown by category
- Daily average spending
- Comparison with previous month
- Total expenses for current week
- Day-by-day breakdown
- Top spending categories
- Daily average
- Expenses grouped by category
- Percentage of total spending per category
- Sorted by amount (highest first)
Administrators have elevated access:
- View all users' transactions
- Create, edit, and delete system categories
- Access all budgets and reports
- Override ownership restrictions
Regular users can only:
- View and manage their own transactions
- Create personal categories
- Manage their own budgets
- View their own reports
- User entity with authentication fields
- Category entity with owner field and system category support
- Transaction entity with type, amount, description, date
- Budget entity with limit, month, year, unique constraints
- All migrations executed
- TransactionVoter for VIEW, EDIT, DELETE, CREATE permissions
- CategoryVoter for system vs personal category access
- BudgetVoter for owner and admin access control
- CreateTransactionDto with validation
- UpdateTransactionDto with optional fields
- TransactionFilterDto for query parameters
- CreateBudgetDto and UpdateBudgetDto
- TransactionRepository with filtering and pagination
- findByUserAndPeriod method
- findByUserAndDateRange method
- getTotalByUserAndPeriod method
- getTotalByUserCategoryAndPeriod method
- BudgetRepository with findByUserAndMonth
- TransactionService with create, update, delete, getFiltered, getAllForUser, getByType, getByCategories
- CategoryService with full CRUD operations
- BudgetService with create, update, delete, getUserBudgets
- BudgetAlertService with checkBudgetAfterExpense, getBudgetStatus
- ReportService with getMonthlyReport, getWeeklyReport
- UserProviderService for current user retrieval
- LoggerNotificationService for alert logging
- TransactionController with all CRUD endpoints and filtering
- CategoryController with voter-protected endpoints
- BudgetController with full API routes
- ReportController with monthly, weekly, and budget-status endpoints
- Admin can view all transactions
- Admin-only system category management
- Admin endpoint for viewing any user's data
- System categories to be seeded
- Sample admin and regular user accounts
- Sample transactions and budgets for testing
- API endpoint testing with user tokens
- API endpoint testing with admin tokens
- 403 response verification
- Budget alert trigger testing
- Edge case handling
- Add sorting options (by date, amount, category)
- Cursor-based pagination for large datasets
- Configurable default page size per user
- Add database indexes on frequently queried fields
- Implement query result caching
- Optimize N+1 queries in reports
- Filter by amount range (min/max)
- Filter by description search (partial match)
- Filter by multiple types simultaneously
- Yearly summary reports
- Custom date range reports
- Export to CSV/PDF
- Spending trends and predictions
- Email notifications for budget alerts
- Push notifications support
- Configurable notification preferences
- Recurring transactions
- Transaction tags/labels
- Multiple currency support
- Shared budgets between users
- Transaction attachments (receipts)
- Rate limiting
- API versioning
- OpenAPI/Swagger documentation
- Response caching headers
- Two-factor authentication
- Password reset functionality
- Account lockout after failed attempts
- Audit logging for sensitive operations