API e Web Services

Cos'è un'API

Un'API (Application Programming Interface) è un insieme di regole e protocolli che permette a due applicazioni software di comunicare tra loro. Nel contesto web, le API consentono al frontend di richiedere dati al backend, a servizi di terze parti di integrarsi con il tuo sito e a sistemi diversi di scambiarsi informazioni in modo strutturato.

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.

"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 architetturale più diffuso per le API web. Si basa su sei principi fondamentali:

• 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.

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.

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

Metodi HTTP

I metodi HTTP (detti anche verbi) definiscono l'azione da eseguire sulla risorsa. Ogni metodo ha una semantica precisa:

• 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).

Comprendere i metodi HTTP è essenziale anche per interpretare gli status code restituiti dal server.

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

La maggior parte delle API richiede autenticazione per identificare il client e proteggere i dati. I metodi più comuni sono:

• 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 tipici sono:

• 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 più diffuso per testare e documentare API. Permette di inviare richieste HTTP, ispezionare le risposte, salvare collezioni di endpoint e automatizzare i test.

• 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.

Per approfondire come i dati vengono archiviati lato server, consulta le guide sui database SQL e NoSQL.