Standard API GovStack (Esempla Systems) — NORMATIV

Acest conținut nu este încă disponibil în limba selectată.

Toate sistemele dezvoltate respectă obligatoriu acest standard. Scop: când integrăm, știm exact unde și ce metode există; când colectăm metrici/health, fiecare sistem expune aceleași endpoint-uri și același format. Conformitatea e verificată periodic și în CI (vezi „Guvernanță”).

Cerințe sursă: CU-API-001..006 din cerinte-universale.md.

1. Structura URL

https://<host>/api/v{N}/<zonă>/<resursă>[/<id>][/<sub-resursă>]

v{N} = versiune majoră (v1, v2). Major nou DOAR la breaking change.
<zonă> = audiența/segmentul (vezi §2).
<resursă> = substantiv la plural, lowercase, kebab-case. Fără verbe în cale (acțiunea = metoda HTTP).
Endpoint-urile operaționale (health/metrics/info/openapi) NU sunt versionate și NU stau sub /api (vezi §6).

Exemple corecte: GET /api/v1/citizen/requests · POST /api/v1/staff/requests/{id}/approve (acțiune business ca sub-resursă verb-substantiv permisă) · GET /api/v1/public/services Greșit: /api/v1/getRequests, /v1/Requests, /api/requests (lipsă versiune/zonă).

2. Zone (segmente de audiență)

Zonă	Prefix	Cine	Auth	RBAC	Expunere	Note
public	`/api/v1/public`	oricine, anonim	niciuna/minimă	—	ingress public	doar date publice; rate-limit strict (`CU-SEC-005`)
citizen	`/api/v1/citizen`	cetățean autenticat	MPass	acces la propriile date	ingress public	scope „self”; nu vede date ale altora
staff	`/api/v1/staff`	funcționari	MPass + rol	RBAC pe roluri	ingress intern/VPN	acțiuni operaționale
admin	`/api/v1/admin`	administratori	MPass + rol înalt	RBAC + 4-ochi (`CU-RBAC-003`)	intern restricționat	config, roluri, audit
app	`/api/v1/app`	sistem-la-sistem (M2M)	client credentials / token de serviciu	scope per client	intern / MConnect	integrări, webhooks, joburi

Reguli pe zone:

O resursă apare în zona corespunzătoare audienței; aceeași entitate poate avea reprezentări diferite per zonă (ex. public vede mai puține câmpuri decât staff).
Niciodată nu amesteca audiențe pe același prefix. Autorizarea se aplică în plus față de zonă (zona NU înlocuiește RBAC).
app e pentru integrări automate (inclusiv prin MConnect), nu pentru UI.

3. Metode & semantică

GET (citire, sigur, idempotent), POST (creare/acțiune), PUT (înlocuire), PATCH (modificare parțială), DELETE (ștergere).
Idempotență pe scrieri expuse extern via antet Idempotency-Key (CU-API-002).
Acțiunile de business care nu sunt CRUD: sub-resursă imperativă, ex. POST /staff/requests/{id}/approve.

4. Coduri de status (set standard)

200 OK · 201 Created · 202 Accepted (async) · 204 No Content · 400 validare · 401 neautenticat · 403 fără drept (RBAC) · 404 inexistent · 409 conflict · 422 semantică invalidă · 429 rate-limit · 5xx eroare server.

5. Convenții de payload

Content-Type application/json; charset=utf-8.

Erori = RFC 7807 (problem+json):

{ "type":"https://errors.esempla/...", "title":"...", "status":400,
  "detail":"...", "instance":"/api/v1/...", "correlationId":"...", "errors":[] }

Paginare (liste): ?page=<n>&size=<m> (sau cursor pentru volume mari) + plic:
```
{ "items":[...], "page":1, "size":20, "total":135 }
```
Filtrare/sortare: ?filter[field]=val&sort=field,-other.
Localizare: antet Accept-Language: ro|ru (CU-I18N-001).
Corelare: antet X-Correlation-Id acceptat și propagat în logs/trace (CU-OBS-001).
Date/ore în ISO 8601 UTC. Identificatori opaci (nu expune ID-uri interne secvențiale dacă e sensibil).

6. Endpoint-uri operaționale (NEversionate, standard pe TOATE sistemele)

Așezate la rădăcină, ca să colectăm health/metrici uniform:

Endpoint	Scop	Format	Folosit de
`GET /health/live`	liveness (procesul trăiește)	`{"status":"UP"}`	K8s liveness (`CU-K8S-001`)
`GET /health/ready`	readiness (dependențele OK)	`{"status":"UP","checks":{"db":"UP","redis":"UP","elasticsearch":"UP","rabbitmq":"UP","storage":"UP"}}`	K8s readiness, LB
`GET /health`	agregat	ca mai sus	dashboards
`GET /metrics`	metrici Prometheus	text/plain expoziție Prometheus	scraping (`CU-OBS-002`)
`GET /info`	versiune/build	`{"service":"...","version":"...","commit":"...","builtAt":"..."}`	inventar
`GET /api/v1/openapi.json`	contract OpenAPI 3.x	JSON	integratori, audit (`CU-API-001`)

Metrici standard (nume + etichete uniforme): http_server_requests_seconds_* (RED), etichete obligatorii service, version, zone, method, route, status. Astfel agregăm cross-sistem fără mapări per proiect.

7. Versionare & deprecare

Adăugiri compatibile (câmpuri noi) → în aceeași versiune majoră.
Breaking change → v{N+1}, cu rulare paralelă a versiunii vechi pe o fereastră de tranziție.
Deprecare semnalată prin antet Sunset: <data> + Deprecation: true și documentată în OpenAPI.

8. Contract OpenAPI (obligatoriu)

Fiecare serviciu publică OpenAPI 3.x complet (toate zonele, scheme, erori RFC7807, securitate per zonă). operationId unic și descriptiv ({zona}.{resursă}.{acțiune}, ex. staff.requests.approve). OpenAPI e sursa pentru teste de contract (TC-COM-API-02) și pentru auditul de conformitate.

9. Guvernanță — regulă periodică de conformitate (`CU-API-006`)

Standardul e verificat automat în CI la fiecare build (gate) ȘI periodic (cadență din config/workplace.json → governance.api_audit_cadence, default săptămânal) pe toate sistemele.
Mecanism: skill api-standard-audit + agent api-governor + comanda /api-audit + scriptul api_audit.py (analizează OpenAPI + sondă live).
Rezultat: raport pe reguli (PASS/WARN/FAIL), issue-uri GitLab pentru abateri (type:api-conformance) și propuneri concrete de ajustare (ex. „redenumește /api/v1/getUsers → /api/v1/staff/users”, „adaugă /health/ready”, „erorile nu respectă RFC7807”).
api-governor poate propune și evoluții ale standardului însuși când observă pattern-uri recurente — supuse aprobării govstack-architect/teamlead (batch).

Checklist operațional de conformitate: standard-api-checklist.md (același skill).