Skip to content

About

Personal budget management API with FastAPI + PostgreSQL

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

Budget API

English · Azərbaycanca


English

A RESTful API for personal budget tracking. It records customers and their income and expense transactions, filters them by date and type, and reports balances per customer and across the whole system.

Built with FastAPI, SQLAlchemy, PostgreSQL and Pydantic.

Project structure

main.py        FastAPI app and endpoints
models.py      SQLAlchemy models (Customer, Transaction)
schemas.py     Pydantic schemas for validation and responses
database.py    Database connection and session handling
.env           Connection settings (not committed)

Setup

Start PostgreSQL, then create the database:

CREATE DATABASE budget_db;

Install the packages:

uv pip install -r requirements.txt

Create a .env file in the project folder and put your own PostgreSQL password in place of PASSWORD:

DATABASE_URL=postgresql://postgres:PASSWORD@localhost:5432/budget_db

Run the server:

uvicorn main:app --reload

The tables are created on first start. Swagger UI opens at http://127.0.0.1:8000/docs

Endpoints

Customers

Method Path What it does
POST /customers/ Creates a customer (name, surname, start_balance)
GET /customers/ Lists all customers
GET /customers/balances Per-customer report for a period. Filters: start_date, end_date
GET /customers/{id}/summary One customer's income, expense and current balance
DELETE /customers/{id} Deletes a customer, unless they still have transactions

Transactions

Method Path What it does
POST /transactions/ Creates a transaction (customer_id, amount, type, category, created_at)
GET /transactions/ Filters: start_date, end_date, customer_id, type
DELETE /transactions/{id} Deletes a transaction

Report

Method Path What it does
GET /budget/summary Total income, total expense and the difference across all customers

Example

Creating an expense of 150 for customer 1:

POST /transactions/

{
  "customer_id": 1,
  "amount": "150.00",
  "type": "Xərc",
  "category": "market",
  "created_at": "2026-03-15T10:00:00"
}

The response carries the new id and the customer it belongs to:

{
  "customer_id": 1,
  "amount": "150.00",
  "type": "Xərc",
  "category": "market",
  "created_at": "2026-03-15T10:00:00",
  "id": 7,
  "customer": {
    "name": "Rəşad",
    "surname": "Məmmədov",
    "start_balance": "1500.00",
    "id": 1
  }
}

created_at is optional. Leave it out and the server stamps the current time. Money fields go in and come back as strings.

Business rules

type accepts only "Gəlir" or "Xərc". amount must be positive and carry at most two decimals. start_balance cannot be negative.

An expense larger than the customer's current balance returns 400. Deleting an income that would push the balance below zero also returns 400, as does deleting a customer who still has transactions. A missing customer returns 404.

Current balance is start_balance plus income minus expenses.

Design decisions

The balance check uses the current total, not the balance at the transaction's date. Back-dating an expense to January checks today's balance, not January's. A date-aware check would let a record added later invalidate transactions that already went through.

/budget/summary ignores start_balance. It sums recorded transactions only. Starting balances show up per customer in /customers/{id}/summary.

Money is stored as Decimal (Numeric(12,2)), not float. Float cannot represent decimal fractions exactly, so sums drifted: adding 500, subtracting 499.99 and adding 0.01 produced 0.01999999999998181 instead of 0.02. All money fields come back as strings in JSON so the precision survives the round trip.

Error handling

Code When
422 Validation failed: wrong type, negative amount, bad type, bad date format
404 Customer or transaction not found
400 Business rule violated, such as insufficient funds
500 Database error, session rolled back

Azərbaycanca

Şəxsi büdcə uçotu üçün RESTful API. Müştəriləri və onların gəlir/xərc əməliyyatlarını qeyd edir, tarix və növ üzrə filtrləyir, həm ayrıca müştəri, həm bütün sistem üzrə balans hesabatı verir.

FastAPI, SQLAlchemy, PostgreSQL və Pydantic üzərində qurulub.

Layihə strukturu

main.py        FastAPI tətbiqi və endpoint-lər
models.py      SQLAlchemy modelləri (Customer, Transaction)
schemas.py     Validasiya və cavab formaları üçün Pydantic sxemləri
database.py    Baza qoşulması və sessiya idarəetməsi
.env           Qoşulma məlumatları (repoya daxil deyil)

Quraşdırma

PostgreSQL-i işə salın, sonra bazanı yaradın:

CREATE DATABASE budget_db;

Paketləri quraşdırın:

uv pip install -r requirements.txt

Layihə qovluğunda .env faylı yaradın, PAROL yerinə öz PostgreSQL parolunuzu yazın:

DATABASE_URL=postgresql://postgres:PAROL@localhost:5432/budget_db

Serveri işə salın:

uvicorn main:app --reload

Cədvəllər ilk işə salmada yaranır. Swagger UI: http://127.0.0.1:8000/docs

Endpoint-lər

Müştərilər

Metod Yol Nə edir
POST /customers/ Müştəri yaradır (name, surname, start_balance)
GET /customers/ Bütün müştəriləri siyahılayır
GET /customers/balances Hər müştəri üçün dövr hesabatı. Filtrlər: start_date, end_date
GET /customers/{id}/summary Bir müştərinin gəliri, xərci və cari balansı
DELETE /customers/{id} Müştərini silir, əməliyyatı qalmayıbsa

Əməliyyatlar

Metod Yol Nə edir
POST /transactions/ Əməliyyat yaradır (customer_id, amount, type, category, created_at)
GET /transactions/ Filtrlər: start_date, end_date, customer_id, type
DELETE /transactions/{id} Əməliyyatı silir

Hesabat

Metod Yol Nə edir
GET /budget/summary Bütün müştərilər üzrə ümumi gəlir, xərc və fərq

Nümunə

1 nömrəli müştəri üçün 150 məbləğində xərc yaratmaq:

POST /transactions/

{
  "customer_id": 1,
  "amount": "150.00",
  "type": "Xərc",
  "category": "market",
  "created_at": "2026-03-15T10:00:00"
}

Cavab yeni id-ni və əməliyyatın aid olduğu müştərini qaytarır:

{
  "customer_id": 1,
  "amount": "150.00",
  "type": "Xərc",
  "category": "market",
  "created_at": "2026-03-15T10:00:00",
  "id": 7,
  "customer": {
    "name": "Rəşad",
    "surname": "Məmmədov",
    "start_balance": "1500.00",
    "id": 1
  }
}

created_at məcburi deyil. Göndərməsəniz server cari vaxtı yazır. Pul sahələri həm gedərkən, həm qayıdarkən sətir formasındadır.

Biznes qaydaları

type yalnız "Gəlir" və ya "Xərc" qəbul edir. amount müsbət olmalı və ən çox iki onluq rəqəm daşımalıdır. start_balance mənfi ola bilməz.

Cari balansdan böyük xərc 400 qaytarır. Balansı mənfiyə salacaq gəlirin silinməsi də 400 verir, əməliyyatı qalan müştərinin silinməsi də. Olmayan müştəri 404 qaytarır.

Cari balans start_balance üstəgəl gəlirlər, çıx xərclər.

Verilmiş qərarlar

Balans yoxlaması cari ümumi balansa baxır, əməliyyatın tarixindəki balansa yox. Yanvar tarixi ilə yazılan xərc bugünkü balansı yoxlayır, yanvardakını yox. Tarixə həssas yoxlama sonradan əlavə edilən qeydin artıq keçmiş əməliyyatları ləğv etməsinə yol açardı.

/budget/summary start_balance-ı saymır. Yalnız qeydə alınmış əməliyyatları cəmləyir. Başlanğıc balanslar müştəri səviyyəsində, /customers/{id}/summary-də görünür.

Pul Decimal (Numeric(12,2)) kimi saxlanılır, float kimi yox. Float onluq kəsrləri dəqiq ifadə etmir, ona görə cəmlər sürüşürdü: 500 əlavə edib 499.99 çıxıb 0.01 əlavə edəndə 0.02 yerinə 0.01999999999998181 alınırdı. JSON cavablarında bütün pul sahələri sətir kimi qayıdır ki, dəqiqlik yolda itməsin.

Xəta idarəetməsi

Kod Nə vaxt
422 Validasiya pozuldu: yanlış tip, mənfi məbləğ, yanlış type, yanlış tarix formatı
404 Müştəri və ya əməliyyat tapılmadı
400 Biznes qaydası pozuldu, məsələn vəsait çatmır
500 Baza xətası, sessiya geri qaytarılır

About

Personal budget management API with FastAPI + PostgreSQL

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages