Cos'è un'API (application programming interface)?

Le API espongono solo i dati e le funzionalità necessarie per una specifica interazione, mantenendo nascosti altri dettagli interni dell'implementazione. Questa astrazione protegge l'integrità del sistema e semplifica il modo in cui i componenti software comunicano.

Esistono molti tipi di API (API hardware e firmware, API del sistema operativo, API di librerie e framework, API web e altro ancora) e, ad alto livello, funzionano tutte allo stesso modo: definiscono un contratto tra due software, specificando cosa può essere richiesto e restituito.

In quanto spiegazione incentrata sull'integrazione, questo articolo si concentra principalmente sulle API web (un tipo di API che consente al software di effettuare richieste su una rete, spesso utilizzando HTTP), su come funzionano, sulle loro differenze e su come vengono utilizzate per connettere i sistemi, sincronizzare e automatizzare i workflow.

È utile pensare alla comunicazione API in termini di richiesta e risposta tra client e server. L'applicazione che invia la richiesta è il client e il server fornisce la risposta. L'API definisce i termini della comunicazione fra essi.

Per fare un esempio semplice, consideriamo l'elaborazione dei pagamenti di terze parti. Quando un utente acquista un prodotto su un sito di e-commerce, il sito potrebbe offrire l'opzione di "Pagare con PayPal." Per la connessione, questa funzione si affida alle API.

• Quando l'acquirente clicca sul pulsante di pagamento, viene avviata una chiamata API. Questa richiesta viene elaborata da un'applicazione al server web attraverso l'Uniform Resource Identifier (URI) dell'API e include un verbo di richiesta, intestazioni e, talvolta, un corpo della richiesta. Insieme, questi elementi specificano cosa viene richiesto e come.
  
  
• Dopo aver ricevuto una richiesta valida dal client, l'API inoltra la richiesta al programma esterno o al server web, in questo caso, il sistema di pagamento di terze parti, e restituisce una risposta con le informazioni richieste.
  
  
• L'API trasferisce i dati all'applicazione richiedente iniziale, in questo caso il sito web del prodotto.

Per l'utente finale, l'intero scambio è invisibile: vede semplicemente una conferma di pagamento accettata.

Le API sono presenti a ogni livello del software, da quello più vicino all'hardware fino ai servizi web con cui la maggior parte delle persone interagisce quotidianamente. In molte conversazioni quotidiane, API è usato come sinonimo di API web. Ma esistono molti tipi di API che servono diversi casi d'uso, tra cui:

• Le API hardware e firmware permettono al software di comunicare con i componenti fisici di un dispositivo, come processori e sensori.
  
  
• Le API del sistema operativo consentono al software di comunicare con il sistema operativo per servizi come la gestione di file, processi e memoria.
  
  
• Le API di librerie e framework espongono codice prescritto (funzioni, metodi e hook) con cui gli sviluppatori interagiscono direttamente all'interno delle loro applicazioni senza passare da una rete. 
  
  
• Le API di database permettono al software di comunicare, manipolare ed estrarre le informazioni memorizzate in un database.
  
  
• Le API web permettono al software di effettuare richieste tramite una rete, spesso utilizzando HTTP. Sono un tipo di API remota che facilita la comunicazione e la manipolazione delle risorse tra diverse macchine, piuttosto che tra un singolo dispositivo.

*Vale la pena notare che alcuni sistemi più vecchi espongono i protocolli di rete, come FTP, SMTP e SSH, direttamente come interfaccia di integrazione. Tecnicamente, questi rientrano in una definizione ampia di API, anche se sono categorizzati in base a come comunicano piuttosto che a ciò con cui si interfacciano, e sono meno rilevanti per una discussione focalizzata sull'integrazione.

Le API web sono le più comuni per l'integrazione. A differenza degli altri tipi di API sopra elencati, sono progettate per la comunicazione tra applicazioni separate su una rete.

REST è oggi lo stile di architettura dominante per le API web. Le API REST, note anche come API RESTful, si basano su sei vincoli architettonici guida definiti inizialmente da Roy Fielding per la creazione di servizi web scalabili, flessibili e disaccoppiati.

REST rende i dati disponibili come risorse e le API REST utilizzano metodi HTTP come GET, POST, PUT, PATCH e DELETE per interagire con queste risorse. Ogni risorsa è identificata da un URI unico, comunemente chiamato endpoint API. Questo è l'indirizzo specifico a cui il client invia una richiesta API.

REST è definito dai seguenti vincoli:

• Interfaccia uniforme: crea regole di comunicazione standardizzate: tutte le richieste per la stessa risorsa devono avere lo stesso aspetto. Ogni risorsa dovrebbe avere un URI.
  
  
• Separazione client/server: le applicazioni client e server devono essere in grado di evolversi separatamente, senza dipendenze. L'unica informazione di cui dispone il client è l'URI della risorsa.
  
  
• Condizione stateless: il server non memorizza lo stato della sessione tra una richiesta e l'altra. Ogni richiesta è autonoma e deve includere tutte le informazioni necessarie per elaborarla.
  
  
• Memorizzazione nella cache: tutte le risorse dovrebbero essere memorizzabili nella cache quando possibile, e il server deve dichiarare tali risorse come memorizzabili nella cache.
  
  
• Architettura di sistema a più livelli: poiché ogni richiesta in REST è autonoma, il client non deve sapere se sta comunicando con il server di origine o con un intermediario. Questo rende REST adatto per le API pubbliche che servono molti client.
  
  
• Code on demand (opzionale): le API REST di solito restituiscono dati. Questo vincolo finale (l'unico vincolo opzionale) consente la restituzione di codice eseguibile, come JavaScript, che il client può eseguire quando necessario.

Per una spiegazione più completa dei principi REST, vedi qui.

SOAP è un protocollo di messaggistica basato su XML con standard rigorosi per la struttura e la trasmissione dei messaggi. A differenza delle API REST, che funzionano quasi esclusivamente su HTTP, SOAP è indipendente dal trasporto. Può operare tramite HTTP, SMTP e altri protocolli, risultando quindi più flessibile negli ambienti aziendali in cui HTTP non è sempre il protocollo sottostante.

I messaggi SOAP hanno una struttura rigida che specifica come il messaggio deve essere elaborato, rendendo SOAP più prolisso di REST, ma anche più standardizzato. Gli standard formali di SOAP, la gestione integrata degli errori e le rigide specifiche di sicurezza rimangono preziosi e ne guidano il continuo utilizzo ancora oggi in settori come la finanza e la sanità.

L'RPC precede le API web e ha implementazioni sia legacy che moderne. L'RPC, a volte chiamato chiamata di subroutine o chiamata di funzione, consente a un'applicazione di eseguire una funzione o un metodo su un server remoto come se fosse locale. L'RPC è organizzato in base alle azioni anziché alle risorse. Invece di singoli URI per ogni risorsa, le API RPC tipicamente espongono un singolo endpoint e specificano l'azione all'interno del payload della richiesta.

Il predecessore diretto di JSON-RPC, XML-RPC, utilizza XML per codificare le sue chiamate e risposte. È più vecchio di SOAP ma più semplice, il che ne facilita l'implementazione, sebbene la verbosità di XML lo renda più pesante delle alternative basate su JSON. Fondamentalmente, è un antenato diretto di JSON-RPC.

JSON-RPC funziona allo stesso modo di XML-RPC ma utilizza JSON invece di XML. JSON è più compatto e più facile da analizzare rispetto a XML, il che rende JSON-RPC più leggero e leggibile rispetto al suo predecessore.

gRPC è il livello moderno e ad alte prestazioni della famiglia RPC. Inizialmente è stato sviluppato da Google, è ora gestito come progetto open source. Mentre le vecchie implementazioni RPC utilizzano formati basati su testo, gRPC utilizza Protocol Buffers (o Profobuf), un formato di serializzazione binaria che produce messaggi più piccoli e veloci rispetto a JSON o XML.

Funziona anche su HTTP/2 anziché su HTTP/1.1, aggiungendo ulteriori vantaggi in termini di prestazioni. gRPC è comunemente usato per la comunicazione interna a microservizi e supporta lo streaming bidirezionale, il che lo rende una scelta valida per i flussi di dati in tempo reale.

GraphQL è un linguaggio di query open source e un tempo di esecuzione lato server sviluppato da Facebook nel 2012 per facilitare un recupero più efficiente delle risorse. È progettato per eliminare l'overfetching (ricezione di più dati del necessario) e l'underfetching (che richiede più richieste per ricevere i dati necessari) consentendo ai clienti di specificare esattamente quali dati desiderano. GraphQL utilizza un singolo endpoint attraverso il quale i client possono interrogare più risorse, con i risultati restituiti in un'unica risposta.

Sebbene altamente flessibile, GraphQL è più complicato di REST ed è più utilizzato in ambienti complessi in cui i requisiti dei dati dei clienti variano in modo significativo.

Leggi un confronto più approfondito tra REST e GraphQL qui.

Le API menzionate seguono tutte un modello di richiesta/risposta avviato dal cliente. Vale la pena notare due importanti eccezioni in un contesto di integrazione:

• I WebSocket (API WebSocket) mantengono una connessione persistente e bidirezionale, adatta a casi d'uso in tempo reale come i feed dati in tempo reale.
  
  
• I webhooks invertono completamente il modello: invece che far avviare una richiesta dal cliente, il server invia le notifiche al client quando si verifica uno specifico evento.

Le API pubbliche sono completamente esposte a Internet e sono disponibili a qualsiasi sviluppatore o organizzazione, generalmente senza restrizioni o con restrizioni minime. Agli sviluppatori potrebbe essere richiesto di ottenere una chiave API, ma non serve molto per lavorare con queste API. Sono progettati per incoraggiare l'integrazione esterna e lo sviluppo di terze parti.

*Da non confondere con "OpenAPI Specification (OAS)", di cui puoi trovare maggiori informazioni qui. 

Le API private non sono disponibili al pubblico e sono accessibili solo all'interno di un'organizzazione definita. Sono spesso isolati su reti private e richiedono un'autenticazione rigorosa per l'accesso. Le organizzazioni utilizzano comunemente tali API per collegare sistemi software interni.

Dal punto di vista dell'accesso, le API partner si collocano tra le API pubbliche e private in quanto sono disponibili per un gruppo specifico di business partner autorizzati. Sebbene possano essere raggiunte tramite internet pubblico, non sono disponibili al pubblico e l'accesso è concesso solo agli utenti autorizzati. Le API partner vengono utilizzate per attività come la condivisione di dati B2B o per monetizzare flussi di dati, e il loro utilizzo è spesso regolato da specifici accordi di partnership. 

*Le API composite sono talvolta incluse in questa suddivisione dei tipi di accesso, ma sono meglio intese come un modello architettonico piuttosto che come livello di accesso. Le API composite combinano le chiamate API e possono essere pubbliche, private o partner. Questi argomenti vengono approfonditi nella sezione dedicata alle API e ai microservizi.

La progettazione delle API è il processo decisionale che determina come un'API espone dati e funzionalità. Nel processo di progettazione, i team decidono quali protocolli e stili architettonici utilizzerà l'API, stabiliscono convenzioni coerenti per la denominazione, le strutture di risposta e la gestione degli errori, decidono come l'accesso verrà autenticato e autorizzato e definiscono una strategia di controllo delle versioni per la gestione delle modifiche sostanziali. Queste e molte altre decisioni determinano il funzionamento di un'API e il modo in cui gli sviluppatori interagiscono con essa.

In sostanza, si tratta di un processo che inizia con domande del tipo: "Come verrà utilizzata questa API?" e che procede con lo sviluppo di un blueprint di progettazione per le API che soddisfi le esigenze dell'organizzazione.

Le politiche di governance delle API di un'organizzazione spesso influenzano il design delle API. Per governance delle API si intende l'insieme di criteri, policy e pratiche che informano il modo in cui un'organizzazione sviluppa, distribuisce e utilizza le proprie API. Una progettazione delle API efficace produce API che rispettano queste politiche predefinite.

La documentazione API è come un manuale tecnico di istruzioni che fornisce informazioni su un'API, come protocolli supportati, linguaggi e metodi di autenticazione, frammenti di codice, definizioni strutturali e altre informazioni necessarie affinché gli sviluppatori possano lavorare con un'API. Una documentazione API completa e aggiornata offre agli sviluppatori una migliore esperienza con le API e favorisce l'adozione, l'integrazione e la gestione delle API di successo.

API-first (o API-design first) è un approccio di sviluppo software in cui le API vengono trattate come la base di un'applicazione, progettata prima di scrivere qualsiasi codice dell'applicazione. Invece di iniziare con la logica aziendale di backend e la struttura del database, le organizzazioni definiscono prima il contratto, spesso utilizzando una specifica API come OpenAPI, e costruiscono il resto dell'applicazione attorno ad esso.

È un approccio preferito per le organizzazioni ad alta integrazione, favorito per la sua scalabilità, affidabilità e coerenza: l'API è la fonte di informazioni centrale e tutti i consumatori (app web e mobili, dispositivi Internet of Things (IoT), app e modelli AI e altri sistemi) interagiscono con lo stesso livello API anziché con integrazioni su misura.

Alcune organizzazioni trattano API-design first e API first come approcci distinti, essendo quest'ultima una funzione più ampia a livello di organizzazione che tratta le API come prodotti stessi, con i propri cicli di vita, product manager e roadmap.

L'architettura a microservizi è uno stile architettonico che divide un'applicazione in servizi più piccoli e indipendenti. Questi servizi comunicano tramite API, spesso un mix di protocolli e stili: ad esempio, API REST per servizi rivolti all'esterno, gRPC per la comunicazione interna tra servizi e webhook per flussi guidati dagli eventi. Un'architettura a microservizi offre agli sviluppatori la flessibilità di scegliere il framework che funziona meglio per un determinato servizio.

Consente inoltre agli sviluppatori di testare, distribuire/implementare, aggiornare, integrare, mantenere e scalare i servizi in modo indipendente l'uno dall'altro. L'isolamento dei guasti è semplificato: il malfunzionamento di un singolo componente non causa il blocco dell'intera applicazione. Inoltre, grazie al disaccoppiamento dei servizi, l'implementazione interna può cambiare senza compromettere le integrazioni esistenti.

Un problema comune dei microservizi è il cosiddetto problema del "front-end chiacchierone". In un'applicazione tradizionale, i dati risiedono in un unico database e un client può interrogare questo database con una sola chiamata. Nei microservizi, i dati sono distribuiti su molti servizi, il che può richiedere a un cliente di comunicare con decine di servizi, tramite decine di richieste separate, per ottenere i dati di cui ha bisogno. Le API composite risolvono questo problema presentando un endpoint unificato che funge da livello di orchestrazione, rispondendo a una richiesta del cliente, comunicando con vari servizi backend per raccogliere i dati richiesti e restituendoli al client in un unico payload.

Le API composite eliminano la necessità per i client di effettuare più chiamate di andata e ritorno per una singola operazione. Nascondono anche la complessità interna del sistema: il client non ha bisogno di sapere quale microservizio gestisce quali dati, ma solo come raggiungere l'endpoint composito. E possono ridurre la latenza, poiché una singola chiamata che si basa sulla comunicazione interna a microservizio è in genere più veloce di diverse chiamate di andata e ritorno su una rete esterna.

Nonostante tutti i loro benefici, le architetture dei microservizi ampliano la superficie delle API e aggiungono complessità, sottolineando l'importanza di una gestione delle API solida.

La gestione delle API è il processo di pubblicazione, sicurezza, controllo e monitoraggio delle API durante il loro ciclo di vita. Questo lavoro viene in genere centralizzato tramite una piattaforma di API management che aiuta le organizzazioni ad applicare politiche coerenti a tutte le loro API. Molte di queste piattaforme includono anche strumenti di progettazione e documentazione, anche se questa sezione si concentra sul ruolo operativo della gestione.

La gestione delle API include la supervisione di:

Un API gateway è uno strato software che offre un unico punto di ingresso per permettere ai client di accedere a più servizi backend. Essi impediscono ai client di dover comprendere o interagire con la complessità architettonica dietro il gateway e servono a domare la proliferazione di API create dai microservizi.

Le funzioni chiave includono il routing, l'autenticazione, la limitazione della velocità e il monitoraggio. I gateway possono anche gestire l'aggregazione delle richieste, il che li rende un punto comune per implementare API composite.

La sicurezza delle API è un insieme di pratiche e procedure che proteggono le API e i dati che trasmettono da usi impropri, attacchi di bot dannosi e altre minacce alla cybersecurity.  La sicurezza delle API include l'autenticazione (verifica dell'identità dell'utente), l'autorizzazione (determinazione di cosa possono fare), la crittografia, la convalida degli input e altro ancora. Le tecnologie di sicurezza più comuni includono le chiavi API e OpenID Connect (ODIC) per l'autenticazione e OAuth per l'autorizzazione. Un robusto livello di sicurezza delle API assicura che solo gli utenti e le applicazioni autorizzati possano accedervi. 

La limitazione della velocità e il throttling controllano il volume e il flusso delle richieste API per aiutare a mantenere i sistemi stabili e disponibili. La limitazione di velocità limita il numero di chiamate che un singolo cliente può effettuare in un periodo specificato, e la limitazione gestisce il volume di chiamate accettate da un sistema, generalmente rallentando o mettendo in coda le richieste. Le limitazioni di velocità svolgono anche una funzione commerciale, permettendo alle organizzazioni di imporre livelli di utilizzo per le API a pagamento.

Sebbene siano principalmente questioni operative, sia la limitazione che la regolazione della velocità svolgono un ruolo secondario in termini di sicurezza, contribuendo a contrastare gli attacchi denial-of-service e di credenziali di riempimento.

La gestione delle API applica la strategia di controllo delle versioni stabilita nella progettazione. Le piattaforme di gestione consentono alle organizzazioni di indirizzare il traffico verso la versione corretta dell'API, di eseguire più versioni contemporaneamente e di gestire la deprecazione delle versioni precedenti. Ciò consente ai team di implementare aggiornamenti e nuove versioni, comprese modifiche sostanziali, fornendo al contempo il tempo necessario per la migrazione delle integrazioni esistenti senza interruzioni.

Le API sono il tessuto connettivo dei sistemi aziendali, servizi e partner ed è fondamentale comprenderne il funzionamento. Un'API difettosa può causare problemi di integrazione che dipendono da essa: monitoraggio e observability aiutano i team a rilevare e diagnosticare tali problemi prima che si propaghino a cascata nei sistemi connessi.

Il monitoraggio delle API monitora le prestazioni, la disponibilità, la funzionalità e l'utilizzo delle API, fornendo avvisi quando metriche come latenza o tassi di errore superano soglie predefinite. L'observability si espande con il monitoraggio, utilizzando metriche, registri e tracce per acquisire una comprensione più profonda dello stato del sistema e delle informazioni di superficie che il monitoraggio non contrassegna.

Comprendere l'utilizzo delle API aiuta i team a pianificare la capacità, a risolvere potenziali minacce e a rispettare i requisiti governativi e normativi.

Le API Connect collegano applicazioni software, sistemi e workflow per lo scambio di dati e servizi, una funzione spesso chiamata integrazione di API. Nella maggior parte delle integrazioni moderne, le API sono fondamentali per lo spostamento delle informazioni tra servizi e sistemi.

I casi d'uso più comuni per le imprese includono:

Le API consentono ai team di integrare servizi di terze parti nelle loro applicazioni e workflow. Ad esempio, se un'azienda di salse piccanti vuole includere una mappa di localizzazione dei punti vendita sul proprio sito web che mostra i rivenditori partner, può utilizzare l'API di un'applicazione di mappe per incorporare queste informazioni sul proprio sito.

Le organizzazioni utilizzano le API per condividere dati e servizi con partner, fornitori e clienti. Un'azienda di logistica potrebbe utilizzare un'API per esporre le informazioni di tracciamento degli ordini, così che i rivenditori possano integrarle nei propri sistemi.

Le organizzazioni utilizzano le API per facilitare lo scambio di dati tra i sistemi aziendali, come ad esempio le piattaforme customer relationship management (CRM) e di pianificazione delle risorse aziendali (ERP). Se l'indirizzo di un cliente viene aggiornato in una piattaforma CRM, questa modifica può essere propagata automaticamente tra i sistemi connessi.

Le API vengono utilizzate per accedere a strumenti AI come modelli linguistici di grandi dimensioni (LLM) e modelli di machine learning, e per incorporarli in applicazioni e workflow. L'integrazione dei modelli AI funziona come altre integrazioni di terze parti: invece di dover costruire e addestrare un modello complesso internamente, un team può utilizzare un'API per accedere a un modello esterno.

Gli agenti AI utilizzano le API anche per accedere ai servizi e completare attività, ma funzionano in modo diverso dalle integrazioni tradizionali, in cui uno sviluppatore decide in anticipo quali API chiamare e come chiamarle. Gli agenti AI prendono questa decisione durante il runtime e devono essere liberi di analizzare un problema, scegliere uno strumento ed esplorare le soluzioni rapidamente. Hanno bisogno di un metodo coerente per scoprire gli strumenti e capire come usarli.

Model Context Protocol (MCP), un open source standard introdotto da Anthropic e ora regolato dalla Linux Foundation, collega modelli AI e agenti con applicazioni e sistemi esterni, colmando questa lacuna. I server MCP in genere si trovano sopra le API esistenti come "traduttori universali", e descrivono le funzionalità di uno strumento in un modo standardizzato che qualsiasi applicazione AI compatibile con MCP può utilizzare. Invece di creare un'integrazione personalizzata tra ogni applicazione di AI e ogni strumento, gli sviluppatori possono creare un server MCP per un particolare strumento e renderlo disponibile a qualsiasi agente compatibile. MCP viene spesso paragonato a una porta USB-C per applicazioni di AI, fornendo un unico connettore standard invece di molti connettori personalizzati.

Le applicazioni mobili e web utilizzano le API per comunicare con i loro backend e recuperare dati o attivare azioni senza mai accedere direttamente a database o logiche di business. Un'organizzazione può creare la funzionalità di backend una sola volta e utilizzare le API per servire client web, iOS e Android. Nuovi canali possono essere aggiunti senza dover ricostruire il backend.

Alcune organizzazioni vanno oltre con un approccio backend for frontend che aggiunge livelli sottili specifici per i client sopra API condivise, mantenendo la logica di core business in un unico posto.

Alcune applicazioni non possono aspettare che i clienti richiedano le informazioni. Le API in tempo reale e basate sugli eventi invertono la relazione, inviando le informazioni non appena cambiano o quando si verifica un evento particolare, invece di aspettare che i client richiedano aggiornamenti più volte.

I Webhook notificano i sistemi connessi su eventi specifici, mentre WebSocket e streaming gRPC mantengono connessioni continue per flussi di dati in corso. Insieme, alimentano piattaforme di trading finanziario, sistemi di chat, giochi multiplayer e scambio di dati con sensori IoT, mantenendo i sistemi aggiornati senza la necessità di un polling costante.