API e Web Services

Cos'è un'API

Un'API (Application Programming Interface) è l'insieme di regole con cui due programmi si scambiano dati. Sul web è quello che permette alla pagina che vedi di chiedere informazioni al server, a un servizio esterno di integrarsi con il tuo sito, e a sistemi scritti in linguaggi diversi di capirsi. Quando qualcuno dice «lo colleghiamo via API», sta dicendo questo.

Quando usi un'app meteo sul telefono, quando effettui un pagamento online o quando un sito mostra una mappa Google incorporata, stai interagendo con delle API. Sono il tessuto connettivo del web moderno: ogni volta che servizi diversi si parlano - dal login con Google al checkout con carta di credito - lo fanno attraverso un'API che traduce le richieste in un linguaggio comune e prevedibile.

"Le API sono i contratti digitali tra sistemi software: definiscono cosa puoi chiedere, come chiederlo e cosa aspettarti in risposta."

API REST

REST (Representational State Transfer) è lo stile più diffuso per le API web. Sta su sei principi:

• Client-Server: separazione netta tra chi consuma e chi fornisce i dati.
• Stateless: ogni richiesta contiene tutte le informazioni necessarie; il server non mantiene stato tra le richieste.
• Cacheable: le risposte possono essere messe in cache per migliorare le prestazioni.
• Uniform Interface: le risorse sono identificate da URL e manipolate con metodi HTTP standard.
• Layered System: l'architettura può includere livelli intermedi (proxy, load balancer) trasparenti al client.
• Code on Demand (opzionale): il server può inviare codice eseguibile al client.

# Endpoint REST tipici per una risorsa "prodotti"
GET    /api/prodotti          # Lista tutti i prodotti
GET    /api/prodotti/42       # Dettaglio prodotto con ID 42
POST   /api/prodotti          # Crea un nuovo prodotto
PUT    /api/prodotti/42       # Aggiorna il prodotto 42
DELETE /api/prodotti/42       # Elimina il prodotto 42

SOAP

SOAP (Simple Object Access Protocol) è un protocollo più rigido e strutturato, basato su XML. È ancora usato in ambiti enterprise, bancari e governativi dove servono garanzie formali su sicurezza e transazioni. Il suo punto di forza è il contratto WSDL, un documento che descrive in modo formale ogni operazione disponibile: questo consente la generazione automatica del codice client e una validazione rigorosa dei messaggi. In Italia, ad esempio, molte integrazioni con la Pubblica Amministrazione e con i sistemi di fatturazione elettronica si basano ancora su SOAP. Il prezzo da pagare è una maggiore verbosità e una curva di apprendimento più ripida rispetto a REST.

GraphQL

GraphQL, sviluppato da Facebook nel 2012 e reso open-source nel 2015, è un linguaggio di query per API che permette al client di richiedere esattamente i dati di cui ha bisogno. A differenza di REST, che espone molti endpoint distinti, GraphQL utilizza un singolo endpoint e uno schema tipizzato che descrive tutti i dati disponibili. Il client costruisce la query specificando i campi desiderati, e il server risponde con una struttura JSON identica alla richiesta: nessun campo in più, nessuna chiamata in meno.

# Query GraphQL: richiedi solo nome e prezzo dei prodotti
{
  prodotti {
    nome
    prezzo
    categoria {
      nome
    }
  }
}

Metodi HTTP

I metodi HTTP (o verbi) dicono che azione fare sulla risorsa, e ognuno ha un significato preciso che conviene rispettare:

• GET: recupera una risorsa. Non deve modificare i dati (idempotente e sicuro).
• POST: crea una nuova risorsa. Non idempotente, chiamate ripetute creano risorse duplicate.
• PUT: sostituisce interamente una risorsa esistente. Idempotente.
• PATCH: modifica parzialmente una risorsa. Utile per aggiornare solo alcuni campi.
• DELETE: elimina una risorsa. Idempotente.
• HEAD: come GET, ma restituisce solo gli header (utile per verificare se una risorsa esiste).
• OPTIONS: restituisce i metodi supportati per una risorsa (usato nel CORS preflight).

Conoscere i metodi serve anche a leggere gli status code che il server restituisce: le due cose si spiegano a vicenda.

Il formato JSON

JSON (JavaScript Object Notation) è il formato di scambio dati più diffuso nelle API moderne. Leggibile sia dalle macchine che dagli esseri umani, è supportato nativamente da JavaScript e da praticamente tutti i linguaggi di programmazione.

{
  "id": 42,
  "nome": "Laptop Pro",
  "prezzo": 1299.99,
  "disponibile": true,
  "tag": ["elettronica", "computer", "portatile"],
  "specifiche": {
    "ram": "16GB",
    "storage": "512GB SSD"
  }
}

In JavaScript, JSON.parse() converte una stringa JSON in un oggetto e JSON.stringify() fa l'operazione inversa. La Fetch API gestisce la conversione automaticamente con response.json().

Autenticazione

Quasi tutte le API chiedono di autenticarsi, per sapere chi sei e per proteggere i dati. I modi più comuni:

• API Key: una chiave univoca inviata nell'header o come parametro URL. Semplice ma poco sicura se esposta.
• OAuth 2.0: standard per l'autorizzazione delegata. L'utente autorizza l'app senza condividere la password. Usato da Google, Facebook, GitHub.
• JWT (JSON Web Token): token firmato che contiene informazioni sull'utente. Stateless e ideale per architetture a microservizi.
• Basic Auth: username e password codificati in Base64 nell'header. Da usare solo su HTTPS.

Rate Limiting

Il rate limiting limita il numero di richieste che un client può effettuare in un determinato intervallo di tempo. Serve a proteggere il server da abusi e a garantire un servizio equo a tutti gli utenti.

Gli header di risposta che si incontrano più spesso:

• X-RateLimit-Limit: numero massimo di richieste consentite.
• X-RateLimit-Remaining: richieste rimanenti nella finestra attuale.
• X-RateLimit-Reset: timestamp di reset del contatore.

Se si supera il limite, il server risponde con un 429 Too Many Requests. Per gestire il rate limiting lato client, implementa retry con backoff esponenziale e rispetta l'header Retry-After.

Testare con Postman

Postman è lo strumento con cui si provano le API prima di scrivere codice: mandi la richiesta, guardi la risposta, salvi la raccolta di chiamate e ci costruisci i test. Mezz'ora passata lì dentro fa risparmiare un pomeriggio di tentativi ciechi nel codice.

• Request builder: componi richieste con metodo, URL, header, body e parametri.
• Collezioni: organizza gli endpoint in gruppi logici, condivisibili con il team.
• Variabili d'ambiente: gestisci URL base, token e API key per ambienti diversi (dev, staging, production).
• Test automatici: scrivi asserzioni in JavaScript per verificare status code, tempi di risposta e struttura dei dati.
• Documentazione: genera automaticamente documentazione interattiva dall'API.

Alternative valide a Postman includono Insomnia, Thunder Client (estensione VS Code) e curl da riga di comando per test rapidi.

Da qui si va a vedere dove finiscono i dati, con le guide sui database SQL e NoSQL.