Un'API è una promessa. Appena qualcuno la usa, quella promessa costa cambiarla. Progettare un'interfaccia stabile significa decidere con cura che cosa si promette e che cosa si lascia libero.
Due leggi da tenere a mente
La legge di Hyrum. Con un numero sufficiente di utilizzatori, ogni comportamento osservabile del sistema finirà per essere usato da qualcuno, anche se non documentato. Un ordine di elementi casuale che "funziona sempre nello stesso modo" diventerà una dipendenza. Conseguenza: ciò che non vuoi mantenere, non lasciarlo trapelare.
La regola di una sola versione. Evitare di imporre ai clienti di scegliere tra versioni diverse della stessa cosa. Quando si può, il sistema ha una versione corrente, e le modifiche si fanno in modo compatibile.
Cinque principi
1. Il contratto prima. Si definisce prima l'interfaccia (campi, tipi, errori, esempi), poi la si realizza. Chi usa l'API può cominciare a lavorare sul contratto prima che il codice esista, e le discussioni avvengono quando costano poco.
2. Errori con una semantica coerente. Ogni errore ha la stessa forma in tutta l'API: un codice stabile, un messaggio comprensibile, e dove serve il campo coinvolto. Un'API in cui ogni punto d'ingresso segnala gli errori a modo suo è un'API difficile da usare.
3. Validare ai confini. Si controllano gli input dove entrano nel sistema, non in ogni funzione interna. All'interno si può dare fiducia ai dati già validati.
4. Preferire l'aggiunta alla modifica. Aggiungere un campo opzionale non rompe nessuno; cambiarne il significato o rimuoverlo sì. Le modifiche incompatibili vanno trattate come un evento con preavviso.
5. Nomi prevedibili. Stesse parole per le stesse cose, stesso stile ovunque. Chi ha imparato un punto d'ingresso dovrebbe indovinare gli altri.
Pattern per le API REST
- Risorse. Si modellano sostantivi (ordini, clienti), non verbi; le azioni sono i metodi del protocollo.
- Paginazione. Ogni elenco può crescere: si prevede dall'inizio, con un cursore o un indice.
- Filtri. Parametri espliciti e documentati, con valori predefiniti ragionevoli.
- Aggiornamenti parziali. Un aggiornamento parziale modifica solo i campi inviati e non azzera gli altri.
Pattern per i tipi
- Unioni discriminate per le varianti: un campo che dice di quale tipo si tratta, e i campi che esistono solo per quel tipo.
- Separazione tra ingresso e uscita. Ciò che il cliente invia non coincide con ciò che riceve (l'identificativo lo assegna il sistema).
- Tipi distinti per gli identificativi. Un identificativo di cliente non deve poter essere passato dove ne serve uno d'ordine.
Segnali d'allarme
- L'interfaccia definita a posteriori, descrivendo il codice.
- Errori con forme diverse in punti diversi.
- Validazioni sparse dentro la logica invece che ai confini.
- Campi rimossi o rinominati senza avviso.
- Comportamenti non documentati su cui già si appoggiano i clienti.
- Elenchi senza paginazione.
Un esempio
Un'API restituisce l'importo come numero e un giorno lo si vuole accompagnare dalla valuta. Cambiare il tipo del campo rompe i clienti. Aggiungere un nuovo campo "valuta" accanto a "importo" non rompe nessuno; l'eventuale ritiro del vecchio formato si annuncia con un periodo di transizione.
Quando usarlo
Quando si progettano API, confini tra moduli o qualunque interfaccia pubblica; quando si creano punti d'ingresso REST o GraphQL; quando si definiscono i contratti di tipi tra moduli o tra frontend e backend.
Questo metodo deriva dalla famiglia di skill open source agent-skills di Addy Osmani (licenza MIT), riscritta e adattata.
Questo articolo è una skill di OIAR
Quello che hai letto è il contenuto di una skill del catalogo OIAR, scritto per le persone. Una conoscenza come questa ma più ricca e profonda, scritta per gli agenti, guida le interviste, l'analisi e il report dentro la piattaforma. Le skill si usano in OIAR: per provarla su un tuo progetto serve un account.
api-and-interface-designMetodo per progettare API e interfacce stabili: contratto prima, errori coerenti, validazione ai confini, modifiche additive, nomi prevedibili, pattern REST (risorse, paginazione, filtri, PATCH) e di tipi (unioni discriminate, ingresso e uscita separati, identificativi distinti). Usarla quando si progettano API o confini tra moduli.