Regole di Business - API Design

Questo documento elenca le regole di business fondamentali del dominio API Design, identificate con codice univoco BR-NNN. Ogni regola è technology-independent e descrive un vincolo invariante sul comportamento del sistema.

---

BR-001 - Rate Limiting obbligatorio

Codice: BR-001 Nome: Rate Limiting obbligatorio su ogni endpoint pubblico Descrizione: Ogni endpoint esposto pubblicamente deve applicare un limite di frequenza per proteggere le risorse del server e garantire equità tra i client. Il limite può variare per piano (free/pro/enterprise) ma non può essere assente. Motivazione: Prevenire abusi, Denial-of-Service e consumo iniquo di risorse condivise. Priorità: ALTA Attori: Rate Limiter, API Gateway Violazione: HTTP 429 Too Many Requests con header Retry-After. Tracciabilità: RFC 9110 §15.5.29; OWASP API4:2023.

---

BR-002 - Idempotenza delle operazioni di mutazione sicura

Codice: BR-002 Nome: Le operazioni PUT, PATCH e DELETE devono essere idempotenti Descrizione: Eseguire la stessa operazione di mutazione più volte con lo stesso input deve produrre lo stesso effetto di eseguirla una sola volta. I client devono poter riprovare in sicurezza in caso di timeout di rete senza temere effetti collaterali indesiderati. Motivazione: Garantire robustezza nei confronti di guasti di rete e ritrasmissioni. Priorità: ALTA Attori: Client, Resource Server Eccezioni: POST di solito NON è idempotente; usare Idempotency-Key header per renderlo idempotente. Tracciabilità: RFC 9110 §9.2.2.

---

BR-003 - Versioning esplicito prima di cambiamenti breaking

Codice: BR-003 Nome: Un cambiamento breaking richiede incremento di versione MAJOR Descrizione: Qualsiasi modifica che rompe la compatibilità con client esistenti (rimozione campo, cambio semantica, restrizione validazione) deve essere rilasciata su una nuova versione MAJOR dell'API. La versione precedente deve rimanere operativa per il periodo di deprecazione stabilito. Motivazione: Proteggere i client da regressioni impreviste; rispettare il contratto implicito di stabilità. Priorità: ALTA Attori: API Gateway, Resource Server Tracciabilità: SemVer 2.0.0; Google AIP-180.

---

BR-004 - Autenticazione obbligatoria su risorse non pubbliche

Codice: BR-004 Nome: Ogni risorsa non pubblica richiede un token di accesso valido Descrizione: Le richieste a endpoint protetti devono presentare un token di accesso (es. JWT, OAuth 2.0 Bearer Token) nell'header Authorization. Il server deve verificare firma, scadenza e scope prima di elaborare la richiesta. Motivazione: Prevenire accessi non autorizzati a dati o operazioni sensibili. Priorità: CRITICA Attori: Auth Service, API Gateway Violazione: HTTP 401 Unauthorized per token assente/scaduto; 403 Forbidden per scope insufficiente. Tracciabilità: RFC 6749; RFC 7519; OWASP API1:2023.

---

BR-005 - Paginazione obbligatoria per collezioni non limitate

Codice: BR-005 Nome: Le risorse collezione devono supportare paginazione con limite massimo configurabile Descrizione: Ogni endpoint che restituisce una lista di risorse deve supportare la paginazione (offset o cursore). Il numero massimo di elementi per pagina (page_size) ha un tetto definito dal server (es. 100); richieste oltre il limite vengono troncate o rifiutate con 400 Bad Request. Motivazione: Prevenire esaurimento memoria, timeout e abuso di banda. Priorità: ALTA Attori: Client, Resource Server Tracciabilità: Google AIP-158; RFC 9457 (error format).

---

BR-006 - Contratto degli errori - formato uniforme

Codice: BR-006 Nome: Tutte le risposte di errore devono seguire un formato strutturato uniforme Descrizione: I body degli errori devono includere almeno: tipo di problema (type), titolo leggibile (title), codice HTTP (status), dettaglio testuale (detail) e istanza della richiesta (instance). Nessun dettaglio interno (stack trace, query SQL, path di file) deve trapelare ai client. Motivazione: Facilitare la gestione programmatica degli errori; evitare disclosure di informazioni sensibili. Priorità: ALTA Attori: Resource Server, API Gateway Tracciabilità: RFC 9457 (Problem Details for HTTP APIs).

---

BR-007 - Deprecazione con preavviso minimo

Codice: BR-007 Nome: Un endpoint deprecato deve annunciare la deprecazione con almeno 90 giorni di preavviso Descrizione: Quando un endpoint viene deprecato, il server deve restituire l'header Deprecation (RFC 8594) con la data di rimozione. La documentazione deve essere aggiornata e i client avvisati via changelog e/o email al momento della deprecazione. Motivazione: Dare ai client il tempo di migrare senza interruzioni di servizio. Priorità: MEDIA Attori: Resource Server, Client Tracciabilità: RFC 8594; RFC 9745 (Sunset).

---

BR-008 - Sicurezza TLS obbligatoria su tutti gli endpoint

Codice: BR-008 Nome: Tutta la comunicazione tra client e server deve avvenire su TLS 1.2+ Descrizione: L'API non deve accettare connessioni in chiaro (HTTP). Ogni endpoint deve richiedere TLS 1.2 come minimo; TLS 1.3 è preferibile. I redirect da HTTP a HTTPS sono accettabili ma non sostituiscono il rifiuto diretto delle connessioni non cifrate. Motivazione: Proteggere i token di autenticazione, i dati in transito e garantire integrità della comunicazione. Priorità: CRITICA Attori: API Gateway, Client Tracciabilità: OWASP API2:2023; RFC 9110 §4.2.2.