💰 Expense Tracker API

REST API for personal expense management with JWT authentication.

Project based on roadmap.sh/projects/expense-tracker

📋 Postman Collection

View full collection

---

🚀 Quick Start

# Clone and install
git clone <repo-url>
cd expense-api

# Configure environment variables
cp .env.example .env

# Run
go run cmd/api/main.go

Environment Variables (.env)

PORT=:8080
GIN_MODE=debug
DATABASE_URL=postgres://user:pass@localhost:5432/expenses
JWT_SECRET=your-secure-secret

---

🔐 Authentication

The API uses JWT with two tokens:

Token	Location	Duration	Purpose
Access Token	Header Authorization: Bearer <token>	1 hour	Access protected endpoints
Refresh Token	HttpOnly Cookie refresh_token	24 hours	Get new access token

Authentication Flow

1. POST /users          → Create account (returns access_token + sets refresh_token cookie)
2. POST /auth/login     → Login (returns access_token + sets refresh_token cookie)
3. POST /auth/refresh   → Renew access token (uses cookie, returns new access_token)

---

📡 Endpoints

Health Check

GET /health

Response 200:

{ "status": "ok" }

---

🔑 Auth

Login

POST /auth/login
Content-Type: application/json

{
  "user_email": "user@email.com",
  "password": "mypassword123"
}

Response 200:

{
  "message": "login exitoso",
  "access_token": "eyJhbGciOiJIUzI1NiIs..."
}

Also sets refresh_token cookie (HttpOnly)

Refresh Token

POST /auth/refresh
Cookie: refresh_token=<token>

Response 200:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

---

👤 Users

Create User

POST /users
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@email.com",
  "password": "mypassword123",
  "rol": "admin"
}

Validations:

• email: required, valid email format
• password: required, 8-15 characters
• rol: required, letters and spaces only, 4-10 characters

Response 201:

{
  "id": 1,
  "name": "John Doe",
  "user_email": "john@email.com",
  "rol": "admin",
  "message": "usuario creado exitosamente",
  "access_token": "eyJhbGciOiJIUzI1NiIs..."
}

Get User 🔒

GET /users
Authorization: Bearer <access_token>

Response 200:

{
  "message": "se consulto el usuario exitosamente",
  "user": {
    "id": 1,
    "name": "John Doe",
    "user_email": "john@email.com",
    "rol": "admin"
  }
}

Update User 🔒

PATCH /users
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "John Smith",
  "email": "johnsmith@email.com"
}

Response 202:

{
  "user_id": 1,
  "message": "se actualizo exitosamente el usuario"
}

Delete User 🔒

DELETE /users
Authorization: Bearer <access_token>

Response 202:

{
  "message": "se elimino correctamente el usuario"
}

---

💸 Expenses 🔒

All expense endpoints require Authorization: Bearer <token>

Create Expense

POST /api/expenses
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "amount": 150.50,
  "category": "Food",
  "description": "Lunch at restaurant"
}

Validations:

• amount: required, numeric, >= 1
• category: required, letters and spaces only, 3-15 characters
• description: required, letters and spaces only, 10-50 characters

Response 201:

{
  "expense_id": 1,
  "message": "se creo exitosamente el gasto"
}

Get Expense

GET /api/expenses?id=1
Authorization: Bearer <access_token>

Response 200:

{
  "message": "se obtuvo exitosamente el gasto",
  "expense": {
    "id": 1,
    "user_id": 1,
    "amount": 150.50,
    "category": "Food",
    "description": "Lunch at restaurant",
    "created_at": "2024-01-15T12:00:00Z",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}

Update Expense

PATCH /api/expenses?id=1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "amount": 200.00,
  "category": "Food",
  "description": "Dinner at italian restaurant"
}

Response 202:

{
  "expense_id": 1,
  "message": "se actualizo exitosamente el gasto"
}

Delete Expense

DELETE /api/expenses?id=1
Authorization: Bearer <access_token>

Response 202:

{
  "message": "se elimino correctamente el gasto"
}

Monthly Expense Report

GET /api/expenses/reports?month=2024-01
Authorization: Bearer <access_token>

Response 202:

{
  "message": "reporte generado exitosamente",
  "month": "2024-01",
  "total": 1500.75
}

---

⚠️ Common Errors

Code	Description
400	Invalid input data
401	Token not provided, expired or invalid
403	HTTPS required
404	Resource not found
429	Rate limit exceeded (3 req/20s per IP)
500	Internal server error

Validation error example:

{
  "errors": [
    {
      "field": "password",
      "message": "must be between 8 and 15 characters"
    }
  ]
}

---

🛡️ Security

• ✅ JWT Access Token (Bearer Header)
• ✅ JWT Refresh Token (HttpOnly Cookie)
• ✅ CORS configured (specific origins)
• ✅ Security headers (HSTS, X-Frame-Options, CSP)
• ✅ Rate Limiting (3 req/20s per IP)
• ✅ Strict DTO validation
• ✅ Passwords hashed with bcrypt
• ✅ HTTPS required

---

🏗️ Architecture & Patterns

Hexagonal Architecture (Ports & Adapters)

expense-api/
├── cmd/
│   ├── api/main.go          # Entry point & DI
│   └── middleware/          # HTTP middlewares
├── internal/
│   ├── adapter/
│   │   ├── handler/         # Primary adapters (HTTP controllers)
│   │   └── repository/      # Secondary adapters (DB implementation)
│   ├── core/
│   │   ├── domain/          # Business entities
│   │   └── ports/           # Interfaces (contracts)
│   └── service/             # Application services (use cases)
└── pkg/                     # Shared utilities

Design Patterns

Pattern	Implementation	Location
Repository	Abstracts data access behind interfaces	internal/core/ports/
Dependency Injection	Constructor injection for all services	cmd/api/main.go
DTO (Data Transfer Object)	Separates API contracts from domain	internal/adapter/handler/dto.go
Middleware Chain	Composable request processing	cmd/middleware/
Factory	NewXxxService(), NewXxxHandler() constructors	All layers

Architectural Principles

Principle	How it's applied
Separation of Concerns	Each layer has a single responsibility
Dependency Inversion	Services depend on interfaces, not implementations
Single Responsibility	One handler/service per domain entity
Clean Architecture	Domain has no external dependencies

Layer Responsibilities

┌─────────────────────────────────────────────────────────────┐
│                      HTTP Request                           │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  MIDDLEWARES (cmd/middleware/)                              │
│  • Auth (JWT validation)                                    │
│  • CORS                                                     │
│  • Rate Limiting                                            │
│  • Security Headers                                         │
│  • HTTPS enforcement                                        │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  HANDLERS (internal/adapter/handler/)                       │
│  • Request validation (DTOs)                                │
│  • HTTP response formatting                                 │
│  • Error handling                                           │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  SERVICES (internal/service/)                               │
│  • Business logic                                           │
│  • Orchestration                                            │
│  • Domain rules                                             │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  PORTS (internal/core/ports/)                               │
│  • Repository interfaces                                    │
│  • Contracts for adapters                                   │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  REPOSITORIES (internal/adapter/repository/)                │
│  • Database queries (Bun ORM)                               │
│  • Data mapping                                             │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     PostgreSQL                              │
└─────────────────────────────────────────────────────────────┘

Features Implemented

Category	Feature	Status
Auth	JWT Access Token (Bearer)	✅
Auth	JWT Refresh Token (HttpOnly Cookie)	✅
Auth	Token refresh endpoint	✅
Security	CORS (specific origins)	✅
Security	Security Headers (HSTS, CSP, X-Frame-Options)	✅
Security	HTTPS enforcement	✅
Security	Rate Limiting (per IP)	✅
Security	Password hashing (bcrypt)	✅
Validation	DTO validation with custom validators	✅
Validation	Centralized error handling	✅
Database	Connection pooling	✅
Database	Context with timeout	✅
Logging	Structured logging (zerolog)	✅
Logging	Request/Response logging middleware	✅
Logging	Per-request context logging	✅
Server	Graceful shutdown	✅
Server	Health check endpoint	✅

Database Configuration

// Connection pool settings
MaxOpenConns:    20              // Max simultaneous connections
MaxIdleConns:    5               // Connections kept idle
ConnMaxLifetime: 30 * time.Minute // Connection recycling

---

📦 Dependencies

• Gin - Web framework
• Bun - PostgreSQL ORM
• golang-jwt - JWT
• validator - Validation
• zerolog - Structured logging