🚀 API Service - Clean Architecture

Layanan API modern dengan arsitektur bersih untuk manajemen QRIS

📑 Daftar Isi

• ✨ Fitur Utama
• 🏗️ Arsitektur
• ⚡ Quick Start
• 📊 API Endpoints
• 🛠️ Development
• 🚀 Deployment
• 📚 Dokumentasi

---

✨ Fitur Utama

Core Features

• 📦 CRUD Operations - Operasi lengkap untuk QRIS
• 📖 API Documentation - Swagger/OpenAPI yang interaktif

Developer Experience

• 🔥 Hot Reload - Development dengan auto-restart
• 🐳 Docker Ready - Deployment yang mudah
• ⚡ Code Generator - Buat handler dan model otomatis
• 🧪 Testing Suite - Unit dan integration tests
• 📊 Health Monitoring - Monitoring kesehatan aplikasi

---

🏗️ Arsitektur

Clean Architecture Layers

┌─────────────────────────────────────┐
│           Presentation Layer        │  ← handlers/, routes/
├─────────────────────────────────────┤
│           Application Layer         │  ← middleware/, validators/
├─────────────────────────────────────┤
│              Domain Layer           │  ← models/, interfaces/
├─────────────────────────────────────┤
│          Infrastructure Layer       │  ← database/, external APIs
└─────────────────────────────────────┘

Struktur Project

api-service/
├── 📁 cmd/
│   └── api/main.go                 # 🚪 Entry point aplikasi
├── 📁 internal/                    # 🏠 Core business logic
│   ├── handlers/                   # 🎮 HTTP controllers (Presentation)
│   ├── middleware/                 # 🛡️ Auth & validation (Application)
│   ├── models/                     # 📊 Data structures (Domain)
│   ├── routes/                     # 🛣️ API routing (Presentation)
│   ├── services/                   # 💼 Business logic (Application)
│   └── repository/                 # 💾 Data access (Infrastructure)
├── 📁 tools/                       # 🔧 Development tools
│   └── general/                    # 🎯 General generators
├── 📁 docs/                        # 📚 Documentation
├── 📁 configs/                     # ⚙️ Configuration files
└── 📁 scripts/                     # 📜 Automation scripts

---

⚡ Quick Start

1️⃣ Setup Environment (2 menit)

# Clone repository
git clone <repository-url>
cd api-service

# Setup environment
cp .env.example .env

2️⃣ Pilih Method Setup

🐳 Docker (Recommended)

make docker-run

🔧 Manual Setup

# Install dependencies
go mod download

# Run database migrations
make migrate-up

# Start server
go run cmd/api/main.go

3️⃣ Verify Installation

Service	URL	Status
API	http://localhost:8084/api/v1	✅
Swagger	http://localhost:8084/swagger/index.html	📖
Health Check	http://localhost:8084/api/v1/health	💚

---

📊 API Endpoints

🌍 Public Endpoints

Method	Endpoint	Deskripsi
GET	/api/v1/health	Status kesehatan API

QRIS Management

Method	Endpoint	Deskripsi
GET	/api/v1/qris	List semua QRIS
GET	/api/v1/qris/:id	Get QRIS berdasarkan ID (serial4)
GET	/api/v1/qris/ip/:ip	List semua QRIS berdasarkan IP yang sama
GET	/api/v1/qris/stats	Statistik QRIS

*Semua hanya menampilkan QRIS yang berstatus aktif (value = 1)

Dynamic Query (Advanced)

Method	Endpoint	Deskripsi
GET	/api/v1/qris/dynamic	Query dengan filter dinamis (Semua column termapping)
GET	/api/v1/qris?search=	Advanced Search ketika tidak tahu column yang dicari (Column sementara yang termapping: posdevice, display_name, ip)

Contoh Query:

# Filter berdasarkan Pos Device
# _eq harus exact value dan case sensitive
GET /api/v1/qris/dynamic?filter[posdevice][_eq]=GRANDPAV

# Filter berdasarkan IP
# _contains bisa tidak exact value dan case insensitive 
GET /api/v1/qris/dynamic?filter[ip][_contains]=106

# Kombinasi filter
GET /api/v1/qris/dynamic?filter[ip][_eq]=10.10.150.160&filter[display_name][_contains]=irul

# Pagination dan sorting
# Default Limit 10 dan Offset 0 jika tidak didefinisikan di dalam link
GET /api/v1/qris/ip/dynamic?sort=created_at&limit=5&offset=1

---

🛠️ Development

Code Generation (30 detik)

🎯 Generate CRUD Lengkap

# Generate handler untuk entity baru
go run tools/general/generate-handler.go product get post put delete

# Generate dengan fitur advanced
go run tools/general/generate-handler.go orders get post put delete dynamic search stats

Development Commands

# 🔥 Development dengan hot reload
make watch

# 🧪 Testing
make test           # Unit tests
make itest          # Integration tests
make test-all       # Semua tests

# 📖 Update dokumentasi
make docs           # Generate Swagger docs

# 🔍 Code quality
make lint           # Linting
make format         # Format code

Environment Configuration

📁 .env File:

# Database
BLUEPRINT_DB_HOST=localhost
BLUEPRINT_DB_PORT=5432
BLUEPRINT_DB_USERNAME=postgres
BLUEPRINT_DB_PASSWORD=postgres
BLUEPRINT_DB_DATABASE=api_service

# Application
APP_ENV=development
APP_PORT=8084
LOG_LEVEL=debug

---

🚀 Deployment

🐳 Docker Deployment

Development:

# Start semua services
make docker-run

# Stop services
make docker-down

# Rebuild dan restart
make docker-rebuild

Production:

# Build production image
docker build -t api-service:prod .

# Run production container
docker run -d \
  --name api-service \
  -p 8084:8084 \
  --env-file .env.prod \
  api-service:prod

🔧 Manual Deployment

# Build aplikasi
make build

# Run migrations
./scripts/migrate.sh up

# Start server
./bin/api-service

---

📚 Dokumentasi

📖 Interactive API Documentation

Kunjungi Swagger UI di: http://localhost:8084/swagger/index.html

Cara menggunakan:

✅ Test semua endpoint yang tersedia

🧪 Testing Examples

JavaScript/Axios:

// Fetch data
const qris = await axios.get('/api/v1/qris');
console.log(qris.data);

🔍 Health Monitoring

# Basic health check
curl http://localhost:8084/api/v1/health

# Detailed system info
curl http://localhost:8084/api/v1/health/detailed

Response:

{
  "status": "healthy",
  "timestamp": "2025-09-10T05:39:00Z",
  "services": {
    "database": "connected",
    "bpjs_api": "accessible",
    "satusehat_api": "accessible"
  },
  "version": "1.0.0"
}

---

🚨 Troubleshooting

Masalah Umum

❌ Database Connection Error

# Cek status PostgreSQL
make db-status

# Reset database
make db-reset

# Check logs
make logs-db

❌ Generate Handler Gagal

• ✅ Pastikan berada di root project
• ✅ Cek permission write di folder internal/
• ✅ Verifikasi file internal/routes/v1/routes.go exists

❌ Import Error saat Generate

• 🧹 Jalankan: go mod tidy
• 🔄 Restart development server
• 📝 Cek format import di generated files

Debug Mode

# Enable debug logging
export LOG_LEVEL=debug

# Run dengan verbose output
make run-debug

# Monitor performance
make monitor

---

🎯 Next Steps

📋 Development Roadmap

• ✅ Setup environment selesai
• ✅ Generate handler pertama
• ✅ Test dengan Swagger
• 🔄 Implementasi business logic
• 🔄 Tambahkan unit tests
• 🔄 Setup CI/CD pipeline
• 🔄 Deploy ke production

🚀 Advanced Features

• 📊 Monitoring & Observability
• 🔒 Enhanced Security (Rate limiting, CORS)
• 📈 Performance Optimization
• 🌐 Multi-language Support
• 📱 Mobile SDK Integration

---

⚡ Total setup time: 5 menit | 🔧 Generate CRUD: 30 detik | 🧪 Testing: Langsung via Swagger

💡 Pro Tip: Gunakan make help untuk melihat semua command yang tersedia

---