Quando apri l’applicazione del meteo sul tuo smartphone per controllare se domani pioverà, il tuo telefono non possiede un barometro satellitare né compie complicati calcoli meteorologici in tempo reale. Quando prenoti un viaggio su un portale di comparazione voli, quel sito non possiede aerei né gestisce gli aeroporti mondiali. E quando compri un paio di scarpe online e paghi con PayPal o accedi con il pulsante "Accedi con Google", quel negozio non conosce la password del tuo account Google.
Come fanno applicazioni create da programmatori diversi, residenti su server a migliaia di chilometri di distanza e scritte in linguaggi di programmazione completamente incompatibili tra loro, a dialogare in una frazione di secondo e scambiarsi informazioni in totale armonia?
La risposta è una delle invenzioni più rivoluzionarie dell’era digitale: le API (Application Programming Interface) e i Web Service.
Le API sono i "ponti invisibili" che collegano il software moderno. Senza di esse, ogni programma sarebbe un’isola deserta chiusa in se stessa, incapace di comunicare con il resto del pianeta.
In questa guida didattica esploreremo il mondo delle API con la tecnica di Feynman: partiremo da metafore intuitive (la presa elettrica universale, il menu del ristorante e i mattoncini LEGO) per scoprire cosa sono le API REST, come si legge un messaggio in formato JSON, cosa significano i verbi e i codici di risposta HTTP e come le applicazioni si proteggono con le chiavi API.
💡 Concetto Chiave: Un’API è un contratto formale e un interprete universale: permette a due programmi software di parlarsi e scambiarsi dati senza che l’uno debba sapere come sia fatto o programmato l’altro all’interno.
La Metafora della Presa Elettrica Universale
Per capire un’API non serve pensare al codice. Pensa alla presa di corrente a muro della tua camera:
Quando compri una lampada, un ventilatore o un caricabatterie per smartphone, non devi sapere da quale centrale elettrica arrivi l’energia (se idroelettrica, solare o nucleare) né come sia fatta la complessa rete di trasformatori della città. La compagnia elettrica ti mette a disposizione un’interfaccia standard: due fori nel muro con una tensione garantita di 230 Volt.
Finché la spina del tuo apparecchio rispetta quella forma geometrica, inserisci la spina e l’energia fluisce istantaneamente.
Un’API (Interfaccia di Programmazione delle Applicazioni) fa esattamente la stessa cosa nel mondo del software:
- L’azienda che possiede i dati (ad esempio Google Maps, l’Aeronautica Militare per il meteo, o la banca per i pagamenti) non ti apre le porte di tutti i suoi server segreti.
- Mette a disposizione una "presa standardizzata" e dice agli altri programmatori del mondo: "Se mi mandate una richiesta scritta in questo modo esatto, io vi risponderò con i dati che chiedete".
Il Formato JSON: Il Linguaggio Universale con Cui Parlano le API
Quando due computer si parlano tramite un’API, in quale lingua comunicano? Un server programmato in Python come può farsi capire da un’app per iPhone scritta in Swift?
Usano un formato di testo universale, leggerissimo e comprensibile sia dagli esseri umani sia dai computer: il formato JSON (JavaScript Object Notation).
Un file JSON è semplicemente una lista ordinata di Chiavi e Valori (come una rubrica o una scheda anagrafica), racchiusa tra parentesi graffe:
Guarda quanto è pulito ed elegante! Anche se non hai mai programmato in vita tua, capisci all’istante ogni singolo valore. Qualsiasi linguaggio di programmazione al mondo sa leggere e trasformare questo testo in variabili pronte all’uso in meno di un millisecondo.
Le API REST: Le Regole della Conversazione Web
Oggi lo standard più diffuso in assoluto per creare API su Internet è l’architettura REST (Representational State Transfer), ideata dall’informatico Roy Fielding nel 2000.
Le API REST sfruttano la stessa infrastruttura del web (il protocollo HTTP) e trattano ogni elemento informativo come una Risorsa identificata da un indirizzo web univoco (chiamato Endpoint o URL).
Per interagire con una risorsa, l’API REST usa quattro parole d’azione fondamentali chiamate Verbi HTTP (le cosiddette operazioni CRUD: Crea, Leggi, Aggiorna, Elimina):
| Verbo HTTP | Azione Corrispondente | Esempio di Richiesta Endpoint | Cosa Succede Davvero? |
|---|---|---|---|
| GET | Leggi / Recupera | GET /api/utenti/42 |
Chiedi al server di inviarti la scheda dell’utente numero 42. Non modifichi nulla. |
| POST | Crea / Inserisci | POST /api/utenti |
Invii i dati di un nuovo utente in formato JSON per registrarlo nel database. |
| PUT / PATCH | Modifica / Aggiorna | PATCH /api/utenti/42 |
Aggiorni solo un dato specifico dell’utente 42 (ad esempio il suo nuovo indirizzo email). |
| DELETE | Elimina / Cancella | DELETE /api/utenti/42 |
Ordini al server di cancellare l’account numero 42 dal database. |
I Codici di Stato HTTP: Le Risposte a Tre Cifre del Server
Quando l’API risponde a una chiamata, non si limita a inviare i dati JSON: include un Codice di Stato (Status Code) a tre cifre che spiega all’istante l’esito dell’operazione.
Ecco come interpretare facilmente la "lingua dei numeri":
Sicurezza e Accesso: Le Chiavi API e i Token
Se chiunque potesse mandare richieste a un’API senza limiti, i server delle aziende verrebbero sommersi di traffico abusivo o svuotati dei loro dati proprietari in poche ore.
Per proteggersi, i fornitori di API adottano due meccanismi di sicurezza:
1. La Chiave API (API Key)
È una lunga stringa segreta di caratteri alfanumerici (ad esempio sk_live_99a8b7c6d5e4...) che l’azienda rilascia allo sviluppatore. Funziona come un badge aziendale nominale: ogni volta che la tua app fa una richiesta all’API, deve allegare questa chiave segreta. In questo modo il fornitore sa esattamente chi sta facendo la richiesta, può verificare che tu abbia pagato l’abbonamento e può limitare il numero massimo di richieste al secondo (Rate Limiting).
2. I Token di Accesso e lo Standard OAuth (Login con Google / Apple)
Cosa succede quando usi un’app di terze parti e clicchi su "Accedi con Google"? L’app non deve MAI conoscere la tua vera password di Google.
Grazie al protocollo OAuth 2.0:
- Vieni reindirizzato per un istante sul sito sicuro di Google.
- Inserisci la password su Google e autorizzi l’app a leggere solo il tuo nome ed email.
- Google consegna all’applicazione un Token digitale temporaneo (come un braccialetto VIP di un concerto con scadenza a 1 ora).
- L’app mostra quel token alle API per dimostrare che è stata autorizzata da te, garantendo privacy e sicurezza massime.
Tre Esempi Reali di API che Usi Ogni Giorno Senza Saperlo
Per toccare con mano quanto le API dominino il nostro quotidiano, ecco tre scenari che vivi abitualmente:
Domande Frequenti (FAQ)
1. Che differenza c’è tra una Web API e una libreria software?
Una libreria software (come una libreria grafica in Python o C++) è un pezzo di codice scaricato e installato fisicamente sul tuo computer: gira usando la CPU e la RAM della tua macchina. Una Web API risiede invece su un computer remoto accessibile tramite Internet: per usarla non devi installare nulla sul tuo PC, basta inviare una richiesta di rete via HTTP e attendere che il server remoto compia il lavoro e risponda.
2. Qual è la differenza tra API REST e API GraphQL?
Le API REST hanno endpoint fissi e rigidi: se chiedi /utenti/10, il server ti restituisce l’intero blocco di dati prestabilito (anche campi che forse non ti servivano). GraphQL (tecnologia ideata da Facebook) permette invece al client di chiedere con estrema precisione chirurgica solo i dati esatti desiderati (es. "Dammi solo il nome e la foto dell’utente 10, senza scaricare email e indirizzo"), riducendo drasticamente il consumo di giga su reti mobili.
3. Cosa succede se supero il limite di chiamate consentite di un’API?
Quasi tutte le API gratuite o a pagamento impongono un limite di frequenza (Rate Limiting, ad esempio massimo 100 richieste al minuto). Se il tuo programma supera questo tetto, il server interrompe il servizio e risponde con il codice di errore 429 Too Many Requests (Troppe richieste), costringendo l’applicazione ad attendere qualche secondo prima di riprovare.
4. Esistono API pubbliche e gratuite per fare esperimenti di studio?
Certamente! Esistono migliaia di API pubbliche e totalmente gratuite ideali per gli studenti. Puoi interrogare le API della NASA per scaricare la foto astronomica del giorno, le API di OpenWeather per ottenere il meteo di qualsiasi città della Terra, le API di PokeAPI per creare un’app con tutti i personaggi Pokémon, o le API di Wikipedia per fare ricerche automatiche.
Glossario dei Termini Chiave
- API (Application Programming Interface): Interfaccia standardizzata che consente a due programmi software differenti di comunicare e scambiare dati tra loro.
- API Key: Chiave alfanumerica segreta utilizzata per identificare e autenticare l’applicazione che effettua una richiesta a un web service.
- Endpoint: L’indirizzo URL univoco messo a disposizione dal server dove risiede una specifica risorsa accessibile tramite API.
- JSON (JavaScript Object Notation): Formato di testo aperto e leggero, ampiamente utilizzato nel web per la rappresentazione e lo scambio di dati strutturati a coppie chiave-valore.
- OAuth 2.0: Standard industriale di sicurezza che consente a un utente di autorizzare un’applicazione ad accedere ai propri dati su un altro servizio senza condividere la password.
- Rate Limiting: Meccanismo difensivo che limita il numero massimo di richieste che un client può inviare a un’API entro una finestra temporale definita.
- REST (Representational State Transfer): Stile architetturale per sistemi distribuiti che definisce linee guida per la creazione di servizi web basati sui metodi e codici del protocollo HTTP.
- Verbo HTTP: Metodo formale (GET, POST, PUT, DELETE) che definisce il tipo di operazione che il client intende compiere sulla risorsa individuata dall’endpoint.
Fonti e Riferimenti Accademici
- Fielding, Roy Thomas (2000): Architectural Styles and the Design of Network-based Software Architectures (Chapter 5: Representational State Transfer) — PhD Dissertation, UC Irvine. La nascita storica del modello architetturale REST.
- ECMA International: Standard ECMA-404: The JSON Data Interchange Syntax (ecma-international.org). La specifica tecnica ufficiale del formato universale JSON.
- IETF RFC 7231: Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content — Definizione formale dei metodi d’azione (GET, POST, PUT, DELETE) e dei codici di stato di risposta.
- Hardt, Dick (2012): RFC 6749: The OAuth 2.0 Authorization Framework — Internet Engineering Task Force. Lo standard crittografico per l’autenticazione tramite token per le moderne API web.
- Richardson, Leonard, & Ruby, Sam (2007): RESTful Web Services — O’Reilly Media. Il manuale didattico pionieristico per la progettazione e l’uso pratico delle API sul web.