Design di API per prodotti in continua evoluzione

Modella il dominio, non lo schermo

Le interfacce cambiano più in fretta dei concetti dietro di esse. Un’API costruita intorno a uno schermo specifico tende a esporre stato di presentazione e a forzare endpoint duplicati quando compaiono nuovi client. Parti da risorse di dominio stabili, dal loro lifecycle e dalle operazioni che il business riconosce.

Questo non richiede purezza teorica. Un’API orientata al prodotto può aggregare dati per un journey, ma l’aggregazione deve avere scopo e ownership chiari. Evita di far trapelare direttamente le tabelle del database; la struttura di storage è un dettaglio di implementazione che prima o poi dovrà cambiare.

La compatibilità è una funzionalità

I consumer deployano a ritmi diversi, soprattutto applicazioni mobile e integrazioni esterne. I cambi additivi sono di solito più sicuri: nuovi campi opzionali, nuove risorse e nuovi valori di enum con reader tolleranti. Rimuovere o ridefinire un comportamento esistente richiede un piano di migrazione, telemetria e una data di fine pubblicata.

Il versioning è utile quando le semantiche divergono davvero, ma i numeri di versione non sostituiscono la disciplina di compatibilità. Un’API versionata può ancora sorprendere i consumer con ordinamento cambiato, comportamento di errore, limiti o autorizzazione. Mantieni uno schema machine-readable e testa consumer rappresentativi contro di esso.

• Tratta in sicurezza i valori di enum sconosciuti
• Documenta nullability e default
• Usa contract test per i consumer critici
• Misura l’uso dei campi deprecati prima della rimozione

Le mutazioni hanno bisogno di identità

I retry sono inevitabili su reti inaffidabili. Per le mutazioni importanti, accetta una chiave di idempotenza scoped al caller e all’operazione. Conserva il risultato così una richiesta ripetuta restituisce l’esito originale invece di eseguire di nuovo l’azione.

Il lavoro di lunga durata dovrebbe restituire una risorsa di operazione con stati espliciti. I client possono fare poll o sottoscrivere senza tenere aperta una richiesta fragile. Questo migliora anche il supporto: il sistema può spiegare se il lavoro è in coda, attivo, completato o fallito e perché.

L’autorizzazione appartiene al contratto

L’autenticazione stabilisce l’identità; l’autorizzazione decide se quell’identità può eseguire un’operazione su una risorsa. Applicala sul server al confine significativo più stretto. Nascondere un pulsante nel client è comportamento di interfaccia, non controllo di accesso.

I sistemi multi-tenant hanno bisogno di un contesto di tenant che non possa essere fornito liberamente e fidato dal client. Deriva lo scope dall’appartenenza verificata, valida l’ownership a ogni accesso alla risorsa e registra le azioni amministrative con contesto sufficiente per audit e indagine.

Ottimizza per la comprensione del consumer

Naming coerente, paginazione prevedibile, errori utili, esempi e un change log chiaro riducono il tempo di integrazione più di scelte di protocollo furbe. Un’API ha successo quando i consumer possono usarla correttamente senza imparare la sua storia interna.

Le design review devono includere gli ingegneri client e gli scenari operativi. L’interfaccia vivrà più a lungo della prima implementazione, quindi investi precisione sulle parti più difficili da cambiare: identificatori, semantiche, autorizzazione e lifecycle.