% Specificații API — DiDi Lot 2 (Backend)
% PNRR DIGI150 · contract 11.1.i3.c9

---

# 1. Scop

Lotul 2 expune două servicii cu API documentat prin **OpenAPI 3.0.3**, însumând **374 de
operații**. Prezentul document rezumă structura API-urilor și modul de consultare (Swagger UI).
Specificațiile complete, mașinabile, sunt livrate ca fișiere `openapi.yaml`.

| Serviciu | Port | Operații | Specificație |
|---|---|---|---|
| **Agent V3** (motor de analiză) | 24803 | **87** | `services/orchestration-layer/agent-v3/openapi.yaml` |
| **didiFramework** (parametri) | 3005 | **287** | `services/orchestration-layer/didiFramework/openapi.yaml` |
| **Total** | | **374** | validate cu `openapi-spec-validator` (OK) |

Ambele API-uri sunt protejate prin **JWT RS256** (Keycloak), verificat la gateway (Kong) și în
backend. Autentificarea se face cu header `Authorization: Bearer <token>`.

---

# 2. Agent V3 — API de analiză (87 operații)

Toate endpoint-urile de analiză sunt **asincrone** (dispatch pe RabbitMQ, răspuns `202` + poll).

| Prefix | Rol |
|---|---|
| `/api/v3/pipeline/*` | Pipeline complet: analiză (sync/async), status, istoric, dry-run, resume, cancel |
| `/api/v3/techniques/*` | Detecția tehnicilor de manipulare |
| `/api/v3/ai-tampered/*` | Detecția conținutului generat/modificat de AI |
| `/api/v3/claims/*` | Extragerea + verificarea afirmațiilor |
| `/api/v3/source-assessment/*` | Credibilitatea sursei |
| `/api/v3/domain/*` | Analiza domeniului (WHOIS/DNS/SSL — T4) |
| `/api/v3/media/*` | Upload/download fișiere media (MinIO) |
| `/api/v3/health`, `/api/v3/health/all` | Liveness + health profund cu **toate dependențele Lot 1** |

**Fluxul tipic de analiză:**

1. `POST /api/v3/pipeline/analyze-async` cu `{ media_type, text|url|media_url, user_id }`
   → `202 { session_id, poll_url, result_url }`
2. `GET /api/v3/pipeline/{session_id}/queue-status` → progres
3. `GET /api/v3/pipeline/{session_id}/result` → `AnalysisSession` completă (verdict + componente)

**Integrarea cu Lotul 1** este documentată în specificație prin blocul `x-integrations`
(cele 9 servicii AI consumate, cu variabila de mediu, ținta pe `didi-network` și rolul) și prin
schema `DeepHealthResponse` a endpoint-ului `/api/v3/health/all` — care servește și ca sondă de
integrare live (vezi raportul 04).

---

# 3. didiFramework — API de parametri (287 operații)

CRUD complet pentru toți parametrii platformei (schema `bos_parammgmt`), plus utilizatori,
abonamente și integrarea Keycloak.

| Grup | Rol |
|---|---|
| `/api/techniques`, `/api/dimensions`, `/api/subdimensions`, `/api/indicators`, `/api/validation-rules` | Ierarhia de tehnici de manipulare |
| `/api/verdicts`, `/api/weights`, `/api/risk-levels` | Verdicte, ponderi, niveluri de risc |
| `/api/claims`, `/api/sources`, `/api/platforms` | Claims, surse, platforme |
| `/api/providers/*`, `/api/llm-models` | Provideri LLM, modele, chei API |
| `/api/prompts` | Prompturi per componentă/etapă |
| `/api/sync-redis` | Sincronizarea configurării PostgreSQL → Redis |
| `/api/admin/*` | Utilizatori, roluri, containere, moderare |
| `/api/subscriptions`, `/api/auth/*` | Abonamente, autentificare, credite |

---

# 4. Consultarea interactivă (Swagger UI)

Ambele specificații sunt servite printr-o interfață **Swagger UI** (container `didi-api-docs`),
unde fiecare operație poate fi inspectată și testată. Fiecare operație poartă adnotarea
`x-tested` cu codul HTTP observat la proba live (vezi raportul 03).

Alternativ, fișierele `openapi.yaml` pot fi deschise în orice unealtă compatibilă OpenAPI 3.0
(Swagger Editor, Postman, Insomnia, generatoare de client).

---

# 5. Testare și validare

- **374/374** endpoint-uri cablate și funcționale (raport `03_Raport_Testare_API`).
- Ambele specificații **validate** cu `openapi-spec-validator` (OpenAPI 3.0.3, rezultat OK).
- Securitate verificată: 401 fără token / cu token forjat, 200 cu token valid, RBAC pe operațiile
  sensibile (raport 03 §5).
- Integrarea cu Lotul 1 testată separat (raport `04_Raport_Testare_Integrare_Lot1-Lot2`).