ADR 006 Consult

ADR-006 — API de consultare publică + model de citire pentru consumatori

• Status: Acceptat
• Data: 2026-07-07
• Componentă: web.rest, *QueryService, RegistryConsumer, zone API
• Decidenți: Arhitect platformă GStack, teamlead

Context

GRegistry este citit de mulți consumatori — GPortal (public), GLog, GStorage, GMonitor — și posibil de sisteme externe. Aceștia nu trebuie să vadă sisteme INTERNAL sau TEST, nici sisteme nepublicate. JDL-ul activează filter pe InformationSystem, Environment, PublicationRequest, SystemDependency și paginare pe entitățile grele. Platforma impune standardul API GovStack.

Decizie

Se expune un model de citire filtrat pe vizibilitate, structurat pe zone API conform standardului GovStack:

• GET /api/v1/public/... — zona publică pentru consumatori (GPortal etc.). Întoarce exclusiv sisteme cu visibility = PUBLIC și publishedToPortal = true. Filtrarea este aplicată în stratul de servicii (InformationSystemQueryService), nu lăsată pe seama parametrilor din request — un apelant nu poate „cere” sisteme interne.
• /api/v1/staff/... și /api/v1/admin/... — zone autentificate (OIDC, ADR-002) pentru operatori/administratori; acces la sisteme interne, cereri de publicare, audit.
• Filtrare URL-driven (JPA Criteria + *Criteria) doar pe entitățile declarate filter în JDL; paginare pe InformationSystem, RegistryAudit, Environment, PublicationRequest.
• Endpoint-uri operaționale obligatorii: /management/health/liveness, /management/health/readiness, /management/prometheus (metrics), /api/v1/openapi.json.
• Erori RFC 7807 (application/problem+json) uniforme.
• RegistryConsumer înregistrează consumatorii cunoscuți (cu filterExpression, ex. vis=public) pentru evidență și, opțional, audit al citirilor externe.

Alternative considerate

1. O singură zonă /api cu filtrare pe rol. Respins: standardul GovStack cere zone explicite; separarea reduce riscul de scurgere a datelor interne.
2. Filtrare pe baza parametrilor din client. Respins: nesigur — un consumator ar putea cere visibility=INTERNAL. Filtrul public este server-side, ne-negociabil.
3. Replicare a datelor publice într-un store separat pentru GPortal. Respins pentru v1: complexitate de sincronizare; citirea directă filtrată e suficientă la acest volum.

Consecințe

Pozitive

• Invariant de securitate clar: zona publică nu poate întoarce niciodată sisteme interne/test.
• Contract API standardizat (OpenAPI, RFC 7807, health/metrics) ⇒ integrare ușoară a consumatorilor și audit automat în CI (api_audit.py).

Negative / riscuri

• Cuplare a corectitudinii securității de QueryService; acoperit prin teste pozitive și negative (vezi ../test-scenarios.md).
• Model de autentificare al consumatorilor mașină-la-mașină rămâne decizie deschisă (client-credentials vs. acces public anonim la zona publică) — vezi ../platform_design.md §7.

Legături

• Model: ../../GRegistry.jdl (filter, paginate, RegistryConsumer)
• Design: ../platform_design.md §6 (secvența „GPortal consumă registrul”)
• Depinde de: ADR-002, ADR-004