feat(api): add env config and caching headers

Author: sulujulianto

.env.example

@@ -0,0 +1,11 @@
+# Arahkan ke file data jika butuh override (opsional)
+WILAYAH_DATA_PATH=app/data/wilayah.json
+WILAYAH_METADATA_PATH=app/data/metadata.json
+
+# Konfigurasi aplikasi
+APP_VERSION=0.1.0-api
+PORT=8000
+
+# CORS origins (pisahkan dengan koma jika lebih dari satu)
+# Contoh: https://contoh.com,https://sub.contoh.com
+ALLOW_ORIGINS=

DEPLOYMENT.md

@@ -0,0 +1,35 @@
+# DEPLOYMENT
+
+Panduan singkat menyiapkan **Sistem Wilayah Indonesia API** untuk lingkungan publik.
+
+## Prasyarat
+- Python 3.12+
+- Virtual environment
+- File data bawaan: `app/data/wilayah.json` dan `app/data/metadata.json`
+- (Opsional) Salin `.env.example` menjadi `.env` lalu sesuaikan nilai variabel.
+
+## Menjalankan Lokal / Development
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt -r requirements-dev.txt
+python -m uvicorn app.main:app --host 127.0.0.1 --port ${PORT:-8000} --reload
+```
+
+## Menjalankan Production (single process)
+```bash
+export APP_VERSION=${APP_VERSION:-0.1.0-api}
+export PORT=${PORT:-8000}
+# Atur origins hanya jika perlu CORS publik, mis. ALLOW_ORIGINS=https://example.com,https://sub.example.com
+export ALLOW_ORIGINS=""
+python -m uvicorn app.main:app --host 0.0.0.0 --port "$PORT"
+```
+
+Gunakan reverse proxy (nginx/Caddy) untuk TLS dan buffering jika diperlukan. File data bersifat statis; respons sudah menyertakan `Cache-Control` dan `ETag` untuk efisiensi.
+
+## Deploy ke Platform Umum (garis besar)
+- **Render/Fly.io/Railway**: gunakan Dockerfile yang sudah ada. Set env `APP_VERSION`, `PORT`, `ALLOW_ORIGINS`, dan mount data jika ingin override `WILAYAH_DATA_PATH`/`WILAYAH_METADATA_PATH`.
+- **VM/Bare metal**: buat service manager (systemd/supervisor) yang menjalankan perintah uvicorn production di atas.
+- **Container orchestrator**: gunakan image hasil `docker build -t sistem-wilayah-indonesia-api .` dan ekspos port `8000`.
+
+Pastikan mengecek `/health` dan `/docs` setelah deploy, serta jalankan `make check` pada pipeline sebelum merilis.

README.md

@@ -7,6 +7,10 @@ FastAPI backend + CLI untuk data provinsi/kabupaten/kota. Snapshot dataset 2024-
 - Versi API: 0.1.0-api (branch feat/backend-api)
 - Swagger/OpenAPI: http://127.0.0.1:8000/docs
 
+## Base URL (Production)
+- Placeholder: https://api.example.com
+- Swagger: https://api.example.com/docs
+
 ## Quickstart Lokal
 ```bash
 python -m venv .venv
@@ -28,14 +32,21 @@ Gunakan host 0.0.0.0 hanya untuk container/jaringan jika Anda paham risikonya.
 - GET /v1/provinces/{name} (alias & case-insensitive, 409 jika ambigu)
 - GET /v1/search?q=...&type=all|kabupaten|kota
 
-## Contoh curl (127.0.0.1)
+## Contoh curl (lokal & produksi)
 ```bash
+# Lokal
 curl http://127.0.0.1:8000/health
 curl http://127.0.0.1:8000/v1/stats
 curl http://127.0.0.1:8000/v1/meta
 curl "http://127.0.0.1:8000/v1/provinces?limit=5&offset=0"
 curl http://127.0.0.1:8000/v1/provinces/jabar
 curl "http://127.0.0.1:8000/v1/search?q=bima&type=all"
+
+# Produksi (ganti base URL sesuai deploy)
+BASE_URL=https://api.example.com
+curl "$BASE_URL/health"
+curl "$BASE_URL/v1/meta"
+curl "$BASE_URL/v1/search?q=bima&type=all"
 ```
 
 ## Pengembangan
@@ -49,6 +60,7 @@ mypy app
 - app/data/wilayah.json
 - app/data/metadata.json
 - Catatan: dataset snapshot kompilasi (2024-12) dan belum diverifikasi penuh terhadap dokumen pemutakhiran resmi tahun 2025; untuk kepentingan hukum, rujuk langsung ke instansi pemerintah (lihat DATA_SOURCES.md).
+- Lisensi data mengikuti sumber aslinya dan membutuhkan atribusi yang sesuai; lisensi kode: MIT (lihat LICENSE). DETAIL sumber dan atribusi: DATA_SOURCES.md.
 
 ## Docker / Podman (opsional; CI memverifikasi docker build)
 ```bash
@@ -76,3 +88,4 @@ sistem_wilayah_indonesia.py
 - CHANGELOG: CHANGELOG.md
 - Sumber & metodologi: DATA_SOURCES.md
 - Lisensi: LICENSE
+- Deployment: DEPLOYMENT.md

app/api/deps.py

@@ -1,8 +1,13 @@
 from __future__ import annotations
 
 from app.core.config import settings
+from app.core.cache import compute_etag
 from app.services.metadata_service import MetadataService
 from app.services.wilayah_service import WilayahService
 
 wilayah_service = WilayahService(settings.data_path)
 metadata_service = MetadataService(settings.metadata_path)
+
+
+def get_data_etag() -> str:
+    return compute_etag([settings.data_path, settings.metadata_path])

app/api/v1/meta.py

@@ -1,16 +1,23 @@
 from __future__ import annotations
 
-from fastapi import APIRouter
+from fastapi import APIRouter, Request, Response
 
 from app.api import deps
+from app.core.cache import CACHE_CONTROL_HEADER_VALUE
 from app.core.errors import build_error
 from app.schemas.wilayah import ErrorResponse, Metadata
 
 router = APIRouter()
 
 
 @router.get("/v1/meta", response_model=Metadata, responses={404: {"model": ErrorResponse}})
-async def get_metadata() -> Metadata:
+async def get_metadata(request: Request, response: Response) -> Metadata | Response:
+    etag = deps.get_data_etag()
+    if request.headers.get("if-none-match") == etag:
+        return Response(
+            status_code=304,
+            headers={"ETag": etag, "Cache-Control": CACHE_CONTROL_HEADER_VALUE},
+        )
     try:
         metadata = deps.metadata_service.get_metadata_with_computed(deps.wilayah_service)
     except FileNotFoundError as exc:
@@ -25,4 +32,6 @@ async def get_metadata() -> Metadata:
             code="metadata_invalid",
             message=str(exc),
         ) from exc
+    response.headers["Cache-Control"] = CACHE_CONTROL_HEADER_VALUE
+    response.headers["ETag"] = etag
     return Metadata(**metadata)

app/api/v1/provinces.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
-from fastapi import APIRouter, Query
+from fastapi import APIRouter, Query, Request, Response
 
 from app.api import deps
+from app.core.cache import CACHE_CONTROL_HEADER_VALUE
 from app.core.errors import build_error
 from app.schemas.wilayah import ErrorResponse, Province, ProvinceListResponse
 
@@ -15,11 +16,21 @@
     responses={422: {"model": ErrorResponse}},
 )
 async def list_provinces(
+    request: Request,
+    response: Response,
     limit: int = Query(20, ge=1, le=200),
     offset: int = Query(0, ge=0),
-) -> ProvinceListResponse:
+) -> ProvinceListResponse | Response:
+    etag = deps.get_data_etag()
+    if request.headers.get("if-none-match") == etag:
+        return Response(
+            status_code=304,
+            headers={"ETag": etag, "Cache-Control": CACHE_CONTROL_HEADER_VALUE},
+        )
     items, total = deps.wilayah_service.list_provinces(limit=limit, offset=offset)
     province_models = [Province(**item) for item in items]
+    response.headers["Cache-Control"] = CACHE_CONTROL_HEADER_VALUE
+    response.headers["ETag"] = etag
     return ProvinceListResponse(
         count=total, limit=limit, offset=offset, items=province_models
     )
@@ -30,7 +41,10 @@ async def list_provinces(
     response_model=Province,
     responses={404: {"model": ErrorResponse}, 409: {"model": ErrorResponse}},
 )
-async def get_province(name: str) -> Province:
+async def get_province(
+    name: str, request: Request, response: Response
+) -> Province | Response:
+    etag = deps.get_data_etag()
     province, candidates = deps.wilayah_service.get_province(name)
     if candidates:
         raise build_error(
@@ -45,4 +59,11 @@ async def get_province(name: str) -> Province:
             code="province_not_found",
             message=f"Provinsi '{name}' tidak ditemukan",
         )
+    if request.headers.get("if-none-match") == etag:
+        return Response(
+            status_code=304,
+            headers={"ETag": etag, "Cache-Control": CACHE_CONTROL_HEADER_VALUE},
+        )
+    response.headers["Cache-Control"] = CACHE_CONTROL_HEADER_VALUE
+    response.headers["ETag"] = etag
     return Province(**province)

app/api/v1/search.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
-from fastapi import APIRouter, Query
+from fastapi import APIRouter, Query, Request, Response
 
 from app.api import deps
+from app.core.cache import CACHE_CONTROL_HEADER_VALUE
 from app.schemas.wilayah import ErrorResponse, SearchResponse, SearchResult, SearchType
 
 router = APIRouter()
@@ -14,11 +15,21 @@
     responses={422: {"model": ErrorResponse}},
 )
 async def search(
+    request: Request,
+    response: Response,
     q: str = Query(..., min_length=1),
     search_type: SearchType = Query(SearchType.all, alias="type"),
-) -> SearchResponse:
+) -> SearchResponse | Response:
+    etag = deps.get_data_etag()
+    if request.headers.get("if-none-match") == etag:
+        return Response(
+            status_code=304,
+            headers={"ETag": etag, "Cache-Control": CACHE_CONTROL_HEADER_VALUE},
+        )
     results = deps.wilayah_service.search(q, search_type.value)
     result_models = [SearchResult(**result) for result in results]
+    response.headers["Cache-Control"] = CACHE_CONTROL_HEADER_VALUE
+    response.headers["ETag"] = etag
     return SearchResponse(
         query=q, type=search_type, count=len(result_models), results=result_models
     )

app/api/v1/stats.py

@@ -1,13 +1,22 @@
 from __future__ import annotations
 
-from fastapi import APIRouter
+from fastapi import APIRouter, Request, Response
 
 from app.api import deps
+from app.core.cache import CACHE_CONTROL_HEADER_VALUE
 from app.schemas.wilayah import StatsResponse
 
 router = APIRouter()
 
 
 @router.get("/v1/stats", response_model=StatsResponse)
-async def get_stats() -> StatsResponse:
+async def get_stats(request: Request, response: Response) -> StatsResponse | Response:
+    etag = deps.get_data_etag()
+    if request.headers.get("if-none-match") == etag:
+        return Response(
+            status_code=304,
+            headers={"ETag": etag, "Cache-Control": CACHE_CONTROL_HEADER_VALUE},
+        )
+    response.headers["Cache-Control"] = CACHE_CONTROL_HEADER_VALUE
+    response.headers["ETag"] = etag
     return StatsResponse(**deps.wilayah_service.get_stats())

app/core/cache.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Iterable
+
+CACHE_CONTROL_HEADER_VALUE = "public, max-age=86400"
+
+
+def compute_etag(paths: Iterable[Path]) -> str:
+    hasher = hashlib.sha256()
+    for path in sorted(paths, key=lambda p: str(p)):
+        try:
+            stat = path.stat()
+            hasher.update(f"{path}:{stat.st_mtime_ns}:{stat.st_size}".encode())
+        except FileNotFoundError:
+            hasher.update(f"{path}:missing".encode())
+    return f'W/"{hasher.hexdigest()}"'

app/core/config.py

@@ -3,6 +3,7 @@
 import os
 from dataclasses import dataclass
 from pathlib import Path
+from typing import List
 
 BASE_DIR = Path(__file__).resolve().parent.parent
 
@@ -21,15 +22,55 @@ def _resolve_metadata_path() -> Path:
     return BASE_DIR / "data" / "metadata.json"
 
 
+def _load_dataset_version(metadata_path: Path) -> str:
+    try:
+        if metadata_path.exists():
+            import json
+
+            with metadata_path.open("r", encoding="utf-8") as file:
+                data = json.load(file)
+            if isinstance(data, dict) and "dataset_version" in data:
+                return str(data["dataset_version"])
+    except Exception:
+        # Fallback handled below
+        pass
+    return "unknown"
+
+
 @dataclass
 class Settings:
-    app_name: str = "Sistem Wilayah Indonesia API"
-    version: str = "0.1.0-api"
-    description: str = (
-        "FastAPI service exposing Indonesian provinces, kabupaten, and kota data"
+    app_name: str
+    version: str
+    description: str
+    data_path: Path
+    metadata_path: Path
+    dataset_version: str
+    allow_origins: List[str]
+    port: int
+
+
+def _load_settings() -> Settings:
+    data_path = _resolve_data_path()
+    metadata_path = _resolve_metadata_path()
+    dataset_version = _load_dataset_version(metadata_path)
+    version = os.getenv("APP_VERSION", "0.1.0-api")
+    description = (
+        f"Sistem Wilayah Indonesia API — snapshot dataset {dataset_version}. "
+        "Data provinsi, kabupaten, kota dalam format JSON."
+    )
+    allow_origins_env = os.getenv("ALLOW_ORIGINS", "")
+    allow_origins = [origin.strip() for origin in allow_origins_env.split(",") if origin.strip()]
+    port = int(os.getenv("PORT", "8000"))
+    return Settings(
+        app_name="Sistem Wilayah Indonesia API",
+        version=version,
+        description=description,
+        data_path=data_path,
+        metadata_path=metadata_path,
+        dataset_version=dataset_version,
+        allow_origins=allow_origins,
+        port=port,
     )
-    data_path: Path = _resolve_data_path()
-    metadata_path: Path = _resolve_metadata_path()
 
 
-settings = Settings()
+settings = _load_settings()