API Documentation

Tài liệu REST API của Smart Forecast Backend.

---

Swagger UI

Interactive API Documentation

Backend cung cấp Swagger UI để test API trực tiếp:

• URL: http://localhost:8000/api
• OpenAPI JSON: http://localhost:8000/api-json

Swagger UI cho phép bạn:

• Xem tất cả endpoints với mô tả chi tiết
• Test API trực tiếp từ trình duyệt
• Xem request/response schemas

---

Authentication

Tất cả API endpoints (trừ login/register) yêu cầu JWT token trong header.

Login

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

{
  "email": "user@example.com",
  "password": "password123"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "role": "ADMIN"
  }
}

Sử dụng Token

GET /api/v1/weather/current
Authorization: Bearer <JWT_TOKEN>

Google OAuth (Mobile)

POST /api/v1/auth/google
Content-Type: application/json

{
  "idToken": "google_id_token_from_mobile_app"
}

Lấy thông tin user hiện tại

GET /api/v1/auth/me
Authorization: Bearer <JWT_TOKEN>

Response:

{
  "id": "uuid",
  "email": "user@example.com",
  "name": "Nguyễn Văn A",
  "role": "USER",
  "avatarUrl": "https://...",
  "createdAt": "2025-01-15T10:00:00Z"
}

---

Roles & Permissions

Role	Quyền hạn
ADMIN	Toàn quyền quản lý hệ thống
USER	Xem dữ liệu, nhận cảnh báo, gửi incidents

---

Response Format

Success Response

{
  "data": {...},
  "message": "Success",
  "statusCode": 200
}

Error Response

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Pagination Response

{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

---

Performance Notes

Endpoint	Latency	Cache
/weather/current	100-500ms	Redis 5 phút
/weather/forecast	100-500ms	Redis 30 phút
/weather/history	50-200ms	No cache
/air-quality/current	100-500ms	Redis 5 phút
/incident	20-100ms	No cache
/alert	20-100ms	No cache
/dashboard/summary	50-200ms	Redis 1 phút

---

Testing với cURL

# 1. Login
TOKEN=$(curl -s -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@smartforecast.com","password":"admin123"}' \
  | jq -r '.access_token')

# 2. Get current weather
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/weather/current

# 3. Get air quality history
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/v1/air-quality/history?page=1&limit=10"

# 4. Create alert
curl -X POST http://localhost:8000/api/v1/alert \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Test Alert","severity":"low","type":"weather"}'

# 5. Get dashboard summary
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/dashboard/summary

---

API Sections

API	Mô tả
Weather	Dữ liệu thời tiết hiện tại, dự báo và lịch sử
Air Quality	Chất lượng không khí và AQI
Alert	Quản lý cảnh báo và ngưỡng cảnh báo
Incident	Báo cáo và xử lý sự cố
Stations	Quản lý trạm quan trắc
Ingestion	Thu thập dữ liệu từ nguồn bên ngoài
Users	Quản lý người dùng
Files	Upload và quản lý files
Dashboard	Dữ liệu tổng hợp cho dashboard
Reports	Xuất báo cáo PDF/CSV
Public NGSI-LD	API công khai truy cập dữ liệu NGSI-LD (không cần auth)

---

Tiếp theo

• Data Models - NGSI-LD entities chi tiết
• Hướng dẫn phát triển - Development workflow
• Troubleshooting - Xử lý lỗi