clossers/didi-lot2-backend
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
didi-lot2-backend/backend/docs/07_Specificatii_API_Lot2.md
EVOTECH IT SRL 8ecc78e729 livrare lot 2
2026-07-10 03:39:53 -07:00

4 KiB
Raw Blame History

% 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).