Che cos'è un servizio web?

Un servizio web è un'interfaccia attraverso cui le applicazioni si scambiano dati o richiamano funzioni in rete. Un sito web è pensato soprattutto per essere letto e usato dalle persone; un servizio web espone invece un contratto destinato ai client software. Lo stesso prodotto può offrire entrambi. Molti servizi usano HTTP e JSON, ma il termine comprende anche altri protocolli e formati di dati.

Come funzionano richiesta e risposta

Il client invia una richiesta a un endpoint definito, con un metodo, dei parametri e, se necessario, le credenziali. Il servizio convalida la richiesta, esegue l'operazione e restituisce una risposta. Nelle API HTTP i codici di stato distinguono gli esiti principali: una risposta riuscita, un problema lato client come un input non valido oppure un errore lato server. Il corpo della risposta di solito fornisce maggiori dettagli in un formato documentato.

Un contratto chiaro descrive percorsi, metodi, campi, tipi, autenticazione, limiti di frequenza e condizioni di errore. Grazie a questo contratto i client possono essere sviluppati in modo indipendente. Il versionamento è importante, perché modificare un campo o la sua interpretazione può bloccare le applicazioni esistenti anche se l'indirizzo dell'endpoint resta lo stesso. Mantieni la retrocompatibilità quando l'hai promessa e pubblica i periodi di deprecazione.

Gli stili di interfaccia più comuni

REST è uno stile architetturale, non un unico formato di trasmissione. Le API HTTP definite RESTful di solito rappresentano le risorse tramite URL e usano metodi come GET per la lettura e POST o PUT per le modifiche. Una GET non dovrebbe produrre cambiamenti di stato permanenti, perché client e intermediari possono ripeterla o metterla in cache. SOAP usa messaggi XML strutturati e descrizioni formali dei servizi ed è diffuso in molti sistemi aziendali.

GraphQL permette ai client di richiedere una selezione definita di campi tramite uno schema, spesso su HTTP. Può ridurre il trasferimento di dati superflui, ma aggiunge complessità per quanto riguarda il costo delle query, le autorizzazioni e la cache. I webhook ribaltano il classico schema del polling: è un servizio a chiamare un endpoint registrato quando si verifica un evento. I webhook richiedono l'autenticazione del mittente, la gestione dei nuovi tentativi e la protezione contro le consegne duplicate. Nessuno di questi approcci è il migliore in assoluto.

Sicurezza e privacy

Usa HTTPS per proteggere i dati in transito e verifica il certificato del server. Autentica i chiamanti con uno schema di credenziali adeguato e autorizza separatamente ogni operazione e ogni oggetto. Un token valido dimostra soltanto ciò che il suo ambito consente; non rende sicuro un input qualsiasi. Convalida dimensioni e tipi delle richieste, evita di esporre dati privati nei messaggi di errore e imposta limiti contro gli abusi.

I segreti non devono comparire in URL pubblici, nel codice sorgente lato client o nei log. Ruota le credenziali esposte, limitane l'ambito e usa credenziali distinte per produzione e test. Nelle API che accettano un URL di callback, convalida le destinazioni per impedire richieste verso reti interne. Documenta quali dati personali vengono restituiti e conserva solo quelli necessari.

Affidabilità e prestazioni

Le reti si guastano, quindi i client hanno bisogno di timeout, di un numero limitato di nuovi tentativi e di una gestione chiara dei guasti parziali. Ripetere una lettura è sicuro; ripetere un pagamento o un'altra modifica richiede invece un meccanismo di idempotenza per evitare duplicati. La paginazione limita gli insiemi di risultati troppo grandi. La cache può alleggerire il carico per i dati pubblici stabili, mentre le risposte private o che cambiano rapidamente richiedono una politica di caching attenta.

Chi gestisce il servizio dovrebbe misurare latenza, tassi di errore e disponibilità lungo il percorso reale dei client. Un server può rispondere HTTP 200 e restituire comunque dati incompleti o inutilizzabili, quindi conviene monitorare anche gli esiti di business attesi. I limiti di frequenza proteggono il servizio, ma vanno comunicati in modo prevedibile. Se il servizio è importante per gli utenti, prevedi una pagina di stato o un canale di assistenza per gli incidenti.

Scegliere o costruire un servizio

Parti dall'attività che l'utente deve svolgere e dal contratto dei dati, poi scegli uno stile di interfaccia che i client possano implementare e il team sia in grado di mantenere. Verifica le risposte normali, gli input malformati, le credenziali scadute, i permessi, la paginazione e i timeout. Tieni aggiornati gli esempi e mostra errori concreti. Quando integri un servizio di terze parti, leggi i limiti d'uso, la politica sui dati e gli avvisi di modifica: anche l'endpoint più comodo resta una dipendenza che può guastarsi.