Quando un sito, un’app mobile e un gestionale devono scambiarsi dati senza essere riscritti da zero, entrano in gioco le API. Capire come funzionano aiuta a leggere meglio la documentazione tecnica, scegliere tra REST, SOAP e GraphQL e collegare in modo sicuro applicazioni, database e servizi cloud.
Le idee essenziali per capire le API
- Un’interfaccia permette a software diversi di comunicare attraverso regole definite.
- Una chiamata API comprende normalmente richiesta, elaborazione e risposta.
- REST è spesso la scelta più semplice per applicazioni web e mobile.
- Le API non sostituiscono il database, ma ne controllano l’accesso tramite la logica dell’applicazione.
- Autenticazione, autorizzazione e limiti di traffico sono indispensabili in produzione.
Che cosa sono davvero le API informatiche
Un’API, acronimo di Application Programming Interface, è un insieme di regole che consente a un programma di utilizzare funzioni o dati messi a disposizione da un altro programma. Io la considero una sorta di contratto tecnico: il client sa quale richiesta inviare e il server sa quale risposta restituire.
Il vantaggio è la separazione tra ciò che accade dentro un servizio e ciò che viene esposto all’esterno. Un’applicazione può chiedere il saldo di un conto, l’elenco dei prodotti o la disponibilità di una camera senza conoscere il codice interno, la struttura completa del database o il linguaggio usato dal server.
Client, server ed endpoint
Il client è il programma che invia la richiesta, per esempio un’applicazione Android o una pagina web. Il server riceve la chiamata, esegue la logica necessaria e restituisce un risultato. L’endpoint è l’indirizzo logico associato a una specifica risorsa o operazione.
In una API web, un endpoint potrebbe rappresentare la lista degli ordini oppure il singolo ordine identificato dal numero 125. La richiesta non dovrebbe accedere direttamente alle tabelle del database: passa dal livello applicativo, dove vengono applicate controlli, permessi e regole di business.
Come funziona una chiamata API
Una chiamata tipica usa il protocollo HTTP e contiene almeno un metodo, un indirizzo e, quando serve, alcuni parametri. Per ottenere un prodotto si può usare una richiesta come GET /prodotti/42, mentre per crearne uno nuovo si usa spesso POST con i dati nel corpo della richiesta.
- Il client prepara la richiesta con metodo, endpoint, intestazioni e parametri.
- Il server verifica identità, autorizzazioni e validità dei dati.
- L’applicazione consulta il database o un servizio esterno.
- Il server restituisce una risposta con dati, messaggi e codice HTTP.
La risposta è spesso in formato JSON, più leggero e leggibile rispetto a XML. Un codice 200 indica normalmente un’operazione riuscita, 201 una risorsa creata, 400 una richiesta non valida, 401 credenziali mancanti o errate, 403 accesso negato e 404 risorsa inesistente.
Un errore comune consiste nel considerare sufficiente il codice HTTP. In un progetto reale servono anche messaggi coerenti, identificativi di errore e una struttura stabile, altrimenti il client diventa fragile e difficile da mantenere.
REST, SOAP e GraphQL non sono la stessa cosa
La scelta dipende dal tipo di sistema, dalla compatibilità richiesta e dal livello di controllo necessario. Non esiste un formato migliore in assoluto, anche se per molti nuovi progetti web REST offre il compromesso più pratico.
| Approccio | Come funziona | Quando ha senso | Limiti principali |
|---|---|---|---|
| REST | Usa risorse, URL e metodi HTTP come GET, POST, PUT e DELETE. | Applicazioni web, mobile, microservizi e integrazioni cloud. | Le risposte possono contenere troppi o troppo pochi dati. |
| SOAP | Scambia messaggi XML strutturati secondo un contratto preciso. | Sistemi aziendali, integrazioni legacy e processi con requisiti formali. | È più verboso e spesso più complesso da configurare. |
| GraphQL | Il client specifica i campi di cui ha bisogno tramite una query. | Interfacce ricche che aggregano dati provenienti da più risorse. | Richiede attenzione a caching, autorizzazioni e complessità delle query. |
REST non è un protocollo, ma uno stile architetturale. SOAP, invece, definisce un modello di messaggistica più rigido. GraphQL può ridurre il numero di chiamate necessarie, ma non elimina la complessità: la sposta nella progettazione dello schema e nella gestione delle query.
Il rapporto tra API, database e servizi cloud
In un’applicazione ben progettata, l’API fa da intermediario tra interfaccia utente, logica applicativa e database. Questo permette di impedire che una richiesta esterna esegua direttamente operazioni pericolose o visualizzi colonne che non dovrebbe conoscere.
Immaginiamo un e-commerce. Il client chiede i dati di un prodotto, il server interroga il database, applica eventuali regole di prezzo e restituisce solo nome, prezzo e disponibilità. Campi interni come costo d’acquisto o note del fornitore restano nascosti grazie a una selezione esplicita dei dati.
Integrazioni utili nella pratica
- Un gestionale può inviare fatture a un servizio di contabilità.
- Un’app può usare un gateway per elaborare pagamenti senza memorizzare i dati della carta.
- Una piattaforma cloud può sincronizzare utenti, documenti e permessi con sistemi aziendali.
- Un sistema di analisi può ricevere eventi tramite API e alimentarli in un data warehouse.
La parte più delicata è spesso la sincronizzazione. Se due sistemi modificano lo stesso dato, bisogna stabilire quale sia la fonte autorevole, come gestire i duplicati e cosa accade quando una chiamata fallisce. Una coda di messaggi e operazioni idempotenti, cioè ripetibili senza creare effetti indesiderati, risolvono molti problemi.
Sicurezza e affidabilità devono essere progettate subito
Un’API esposta su Internet è una superficie d’attacco, anche quando dietro c’è un servizio apparentemente semplice. L’autenticazione verifica chi sta effettuando la chiamata, mentre l’autorizzazione stabilisce che cosa quell’utente può realmente fare.
Token OAuth 2.0, JWT e chiavi API possono essere adatti a scenari diversi, ma nessuno di questi strumenti sostituisce i controlli sui dati. Un utente autenticato potrebbe comunque tentare di leggere l’ordine di un altro cliente cambiando semplicemente l’identificativo nell’endpoint.
Tra le protezioni che considero indispensabili ci sono:
- uso obbligatorio di HTTPS;
- validazione rigorosa di parametri e contenuti ricevuti;
- limiti di frequenza per prevenire abuso e consumo eccessivo;
- registrazione degli eventi senza salvare segreti o dati sensibili nei log;
- versionamento delle API quando cambiano i contratti;
- controllo periodico degli endpoint attivi e di quelli ormai obsoleti.
Il progetto OWASP API Security Top 10 richiama rischi come autorizzazioni errate sugli oggetti, configurazioni insicure, gestione incompleta degli asset e consumo illimitato delle risorse. Non è una lista da consultare solo dopo un incidente: dovrebbe guidare già la revisione del progetto e i test automatici.
Come progettare un’API che rimanga utilizzabile
La documentazione non è un accessorio. Una specifica OpenAPI ben mantenuta descrive endpoint, parametri, schemi e risposte e può aiutare a generare documentazione, client e test. Per chi integra il servizio, questo significa meno supposizioni e meno errori.
Leggi anche: Creare un’app Android con Python - Kivy, SQLite e APK
Regole pratiche che fanno la differenza
- Usare nomi coerenti per risorse e campi.
- Definire una forma unica per gli errori.
- Prevedere paginazione per elenchi potenzialmente grandi.
- Stabilire limiti chiari per dimensione e frequenza delle richieste.
- Separare modifiche compatibili da cambiamenti che richiedono una nuova versione.
- Testare casi validi, dati incompleti, permessi insufficienti e timeout.
Uno degli errori più frequenti è restituire sempre tutto. Una risposta enorme rallenta rete e applicazione, aumenta i costi cloud e può esporre informazioni non necessarie. Meglio progettare campi selezionabili, filtri e paginazione, soprattutto quando si lavora con database di grandi dimensioni.
Un altro errore è confondere la documentazione con il comportamento reale. L’API va testata in condizioni simili alla produzione, includendo errori di rete, servizi esterni non disponibili e richieste ripetute. La qualità si misura anche da come il sistema fallisce, non soltanto da quando tutto funziona.
La scelta giusta parte dal contratto e non dal formato
Prima di decidere tra REST, SOAP o GraphQL, chiarisco sempre quali sistemi devono comunicare, quali dati devono viaggiare e quali vincoli di sicurezza esistono. Una piccola applicazione interna può avere bisogno soltanto di pochi endpoint REST, mentre un’integrazione bancaria o assicurativa può richiedere contratti e controlli molto più rigidi.
Il criterio più solido è progettare prima il contratto dell’interfaccia, definire autorizzazioni e casi di errore, poi scegliere strumenti e framework. In questo modo l’API resta comprensibile anche quando cambiano il database, il linguaggio di programmazione o l’infrastruttura cloud.
Per chi sta imparando, suggerisco di partire da un servizio piccolo, documentare tre o quattro endpoint e aggiungere test prima di estendere il progetto. È un approccio meno spettacolare, ma fa emergere subito i problemi che in sistemi più grandi diventano costosi da correggere.
