87 lines
4 KiB
Markdown
87 lines
4 KiB
Markdown
% 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`).
|