Engineering
Best practice per la progettazione di API
Le API coerenti, versionizzate e ben documentate invecchiano bene. I principi che coprono le convenzioni REST, la gestione degli errori, la paginazione e l'autenticazione per mantenere le integrazioni stabili nel tempo.
TL;DR
Un'API ben progettata è volutamente prevedibile: convenzioni coerenti, errori strutturati e un contratto di versioning chiaro. Tagliare i corner su uno qualsiasi di questi aspetti significa accumulare un debito che ogni futura integrazione dovrà ripagare.

Un'API è una promessa. Ogni client che si integra con essa dipende dal fatto che quella promessa venga mantenuta, ed è per questo che le buone api design best practices tendono ad apparire noiose: prevedibili, coerenti, prive di sorprese. Le API che causano problemi sono quelle costruite un endpoint alla volta, ognuno con le proprie convenzioni. Ciò che segue sono i principi che mantengono un'API piacevole da utilizzare e poco costosa da gestire nel corso degli anni.
Essere inflessibilmente coerenti
La coerenza vale più dell'ingegnosità. Si scelgono le convenzioni una volta sola e le si applica ovunque:
- Usare sostantivi per le risorse, non verbi:
GET /invoices/42, nonGET /getInvoice?id=42. - Usare i metodi HTTP per il loro significato effettivo:
GETlegge,POSTcrea,PATCHaggiorna parzialmente,DELETEelimina. - Scegliere un unico stile di scrittura (
snake_caseocamelCase) per i campi JSON e non mescolarli mai. - Restituire la stessa struttura per lo stesso concetto in tutti gli endpoint.
Uno sviluppatore che impara uno dei tuoi endpoint dovrebbe essere in grado di intuire gli altri. È tutto qui. L'incoerenza costringe chi integra a leggere la documentazione per ogni singola chiamata invece di costruire un modello mentale una volta sola.
Progettare gli errori come una funzionalità di primo livello
La maggior parte delle API gestisce perfettamente il percorso felice e trascura i casi di errore. Ed è esattamente lì che chi integra trascorre il proprio tempo di debug. È necessario restituire i codici di stato HTTP corretti (400 per input non valido, 401 vs 403 per l'autenticazione, 404, 409 per i conflitti, 422 per la validazione) e un error body strutturato e leggibile dalle macchine:
``json { "error": { "code": "invalid_email", "message": "Email address is not valid", "field": "email" } } ``
Un campo code stabile su cui i client possono fare branching conta più di un messaggio leggibile. Non esporre mai stack trace ai chiamanti. Se chi integra deve esaminare i log per capire perché la propria richiesta è fallita, significa che il design degli errori li ha già delusi in partenza.
Paginazione e filtri fin dal primo giorno
Qualsiasi endpoint che restituisce una lista finirà prima o poi per restituire troppi elementi. La paginazione va integrata prima che ciò accada, non dopo che i client in produzione dipendono da una risposta illimitata.
La paginazione basata su cursore è più affidabile di quella basata su offset per dataset di grandi dimensioni o in continua evoluzione. La paginazione a offset salta o duplica righe quando i record vengono inseriti o eliminati a metà pagina. Quella a cursore non ha questo problema. È opportuno offrire filtri e ordinamenti ragionevoli come query parameter e impostare sempre un limite massimo alla dimensione della pagina, in modo che un singolo chiamante non possa richiedere tutto in una volta.
Versionare con criterio
Prima o poi sarà necessario introdurre modifiche incompatibili. Meglio accettarlo subito e pianificarlo. Un prefisso nell'URL come /v1/ è semplice ed esplicito: la versione è visibile in ogni richiesta senza dover ispezionare gli header. La regola che mantiene i client sereni è semplice: non rompere mai una versione esistente. È possibile aggiungere campi liberamente, ma non rimuoverli né riutilizzarli per altri scopi. Quando una modifica incompatibile è inevitabile, si rilascia una nuova versione e si offre agli integratori una finestra di deprecazione adeguata, che significa mesi, non giorni.
Sicurezza e rate limiting come impostazione predefinita
Ogni endpoint non pubblico deve essere autenticato con un meccanismo standard. OAuth 2.0 e JWT firmati sono entrambi scelte valide. Non bisogna inventare schemi di autenticazione proprietari. Restituire 429 con un header Retry-After quando i client superano i limiti di frequenza, in modo che possano rallentare gradualmente invece di sovraccaricare il server. Validare e sanificare ogni input; trattare tutti i dati in ingresso come potenzialmente ostili finché non si dimostra il contrario.
Documentare durante lo sviluppo
Un'API non documentata è di fatto privata, anche quando è pubblica. Mantenere una spec OpenAPI insieme al codice permette di generare documentazione, client SDK e validazione delle richieste da un'unica fonte di verità. È fondamentale includere esempi reali di richieste e risposte. Gli sviluppatori copiano gli esempi molto più spesso di quanto leggano le descrizioni in prosa: un esempio funzionante vale più di tre paragrafi di spiegazione.
Se stai progettando un'API con cui dovrai convivere per anni, parliamone.
Domande frequenti
Quali sono le best practice più importanti per la progettazione di API?
Naming coerente e corretto utilizzo dei metodi HTTP, error body strutturati e leggibili dalle macchine, paginazione integrata fin dall'inizio e una strategia di versioning che non rompa mai i client esistenti.
È meglio usare il versioning nell'URL o negli header per una REST API?
Il versioning nell'URL con un prefisso come /v1/ è più semplice ed esplicito. Gli sviluppatori possono vedere la versione in ogni richiesta senza dover ispezionare gli header, il che rende il debug più rapido.
Cos'è la paginazione basata su cursore e quando è opportuno utilizzarla?
La paginazione basata su cursore utilizza un puntatore opaco all'ultimo elemento visualizzato anziché un offset. Non salta né duplica righe quando i record vengono inseriti o eliminati a metà pagina, risultando quindi più affidabile della paginazione a offset per qualsiasi dataset che cambia frequentemente.
Come si documenta correttamente una REST API?
Occorre mantenere una spec OpenAPI insieme al codice, in modo che la documentazione, i client SDK e la validazione delle richieste possano essere tutti generati da un'unica fonte. È fondamentale includere esempi funzionanti di richieste e risposte: gli sviluppatori copiano gli esempi molto più spesso di quanto leggano la prosa.
Come può aiutare Pykero
Servizi collegati a questo articolo.
State costruendo qualcosa di simile?
Pykero Agency progetta e rilascia prodotti web, mobile, SaaS e AI pronti per la produzione.
Parliamone


