Standardul API — NORMATIV

reference/standard-api.md nu e o recomandare. Toate sistemele dezvoltate respectă obligatoriu acest standard, iar conformitatea se verifică în CI. Cerințe sursă: CU-API-001..006.

De ce e normativ, nu stilistic: când integrăm două sisteme, știm fără să întrebăm unde sunt metodele; când colectăm metrici sau health, fiecare sistem expune aceleași endpoint-uri, în același format. Un sistem care „e la fel, dar altfel” costă exact cât unul care nu respectă nimic.

Cele două fișiere, pentru două momente diferite

Fișier	Când
reference/standard-api.md	înainte să scrii — structura URL, zonele, versionarea, formatul de eroare
reference/standard-api-checklist.md	înainte de review — self-check punct cu punct, aceleași puncte pe care le verifică /api-audit

Punctele pe care se cade cel mai des

• Verbe în cale. Resursele sunt substantive plural, kebab-case; acțiunile sunt sub-resurse imperative, nu verbe în URL.
• Audiențe amestecate pe același prefix. Zona (public | citizen | staff | admin | app) e parte din contract, nu decor — RBAC se aplică peste zonă.
• GET /health/live și GET /health/ready confundate. live spune că procesul trăiește; ready verifică dependențele (DB, Redis, ES, RabbitMQ, storage). Un ready care nu verifică nimic e un verde fals, și un verde fals e mai rău decât nicio verificare.
• GET /metrics fără etichetele standard service,version,zone,method,route,status — metrica există dar nu se poate agrega între sisteme, deci nu servește la nimic.
• Versiune majoră nouă fără breaking change. v{N} crește doar la ruptură de contract.

Rolul de gardian

api-governor aplică acest standard; /api-audit îl verifică mecanic. Amândouă citesc de aici — dacă standardul se schimbă, se schimbă într-un singur loc și toată lumea îl primește la următorul git pull al marketplace-ului.