APP_NAME — REST API Python (FastAPI)

App generada desde el Golden Path rest-api/python de Coralware Cove IDP.

Scaffold para API HTTP stateless en FastAPI. Sin persistencia por diseño — si tu app necesita base de datos, migra al shape web-backend/python (que incluye Alembic + MariaDB).

Contrato del shape: ver coralware-shape.yaml. Define los endpoints obligatorios y la versión del shape. No elimines ese archivo — la plataforma lo lee.

---

Estructura

.
├── coralware-shape.yaml          ← contrato con la plataforma
├── catalog-info.yaml             ← entidad Backstage
├── code/
│   ├── app/main.py               ← FastAPI app
│   ├── tests/                    ← pytest + httpx TestClient
│   ├── pyproject.toml
│   ├── requirements.txt
│   └── Dockerfile
├── helm/__APP_NAME__/            ← Helm chart minimal
└── .gitea/workflows/             ← CI: tests + build + deploy

Hooks Helm: el ServiceAccount se materializa como hook pre-install,pre-upgrade (hook-weight: -5, hook-delete-policy: before-hook-creation) por paridad con el shape web-backend/python. Este shape no tiene Job de migración, así que el hook no es estrictamente necesario aquí — se mantiene para que ambos charts sean coherentes. helm upgrade --install funciona sin --no-hooks.

---

Endpoints obligatorios

Path	Auth	Propósito
/health	none	Liveness + readiness; devuelve {status: "ok"}
/docs	configurable	Swagger UI
/openapi.json	configurable	Schema OpenAPI
/metrics	restringido vía NetworkPolicy	Métricas Prometheus

---

Variables de entorno

Variable	Default	Descripción
LOG_LEVEL	INFO	DEBUG para troubleshooting
CORRELATION_ID_HEADER	X-Correlation-ID	Header de trazabilidad
OPENAPI_REQUIRE_AUTH	false	Activar JWT en /docs
KEYCLOAK_ISSUER	—	URL del realm cuando auth activado

---

Desarrollo local

cd code
pip install -r requirements-dev.txt
uvicorn app.main:app --reload --port 8000

Probar:

curl http://localhost:8000/health
curl http://localhost:8000/docs

---

Plan de salida

Sin lock-in técnico:

Componente	Cómo lo exportas
Código	git remote add github && git push github main
Imagen	docker pull desde Harbor + push a tu registry
Manifests	Ya están en helm/ — helm template genera YAML aplicable

---

Cuándo migrar a web-backend/python

Si tu app empieza a:

• Necesitar persistencia (base de datos relacional)
• Usar migraciones de schema
• Servir frontend estático en /demo
• Manejar sesiones o estado entre requests

→ migra al shape web-backend/python (un repo nuevo, un nuevo template).

---

Referencias

• docs/adr-027-product-design-golden-paths.md — Golden Paths Fase 5
• docs/adr-053-shape-web-backend-python.md — anatomía de shapes (referencia)
• docs/adr-038-ci-cd-standardization.md — pipeline Python