Vai al contenuto
Blog

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.

Di Pykero Agency · Engineering team8 lug 20265 min di lettura

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.

Endpoint API puliti che collegano servizi con linee strutturate

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, non GET /getInvoice?id=42.
  • Usare i metodi HTTP per il loro significato effettivo: GET legge, POST crea, PATCH aggiorna parzialmente, DELETE elimina.
  • Scegliere un unico stile di scrittura (snake_case o camelCase) 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.

api design best practicesrest api versioningapi error handlingapi pagination best practicesopenapi documentationapi authentication

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

Discussion

Be the first to comment.

Letture correlate