Programmazione · concetti · web
Cos’è un’API?
Lo senti di continuo: « chiamare l’API », « l’API pubblica », « una chiave API ». Un’API (Application Programming Interface) è una delle idee più utili del software — e una delle più cariche di gergo. Questa guida spiega, in modo semplice, cos’è un’API, i principali tipi che incontrerai, come funziona una tipica richiesta a un’API web e perché le API sono ovunque.
La definizione breve
Un’API è un contratto che permette a un software di comunicare con un altro. Definisce quali richieste puoi fare, quali dati devi inviare e cosa ricevi in cambio — senza che tu debba sapere come l’altra parte è costruita internamente.
L’analogia classica è il ristorante. Tu (un programma) leggi un menù (l’API) e fai un ordine al cameriere. Non entri in cucina e non hai bisogno di sapere come viene preparato il piatto. Il menù è l’interfaccia concordata; la cucina è l’implementazione, nascosta dietro. Un’API è quel menù per il software.
I principali tipi di API
- API web (le più discusse) — un programma parla con un altro attraverso la rete, di solito via HTTP. Quando un’app meteo mostra le previsioni, chiama l’API web di un servizio meteo. La maggior parte delle API web moderne segue lo stile REST e scambia dati in JSON (vedi REST vs GraphQL e gRPC vs REST per le principali alternative).
- API di libreria / framework — l’insieme di funzioni e tipi che una libreria di codice espone perché tu le chiami. Quando usi una libreria di date, le funzioni che ti offre sono la sua API.
- API del sistema operativo — il modo in cui un programma chiede al sistema operativo di aprire un file, disegnare una finestra o usare la rete. POSIX è una di queste.
Il filo conduttore: un’API è la superficie pubblicata di qualcosa, la parte che hai il diritto di usare, separata dai meccanismi interni da cui non dovresti dipendere.
Come funziona una richiesta a un’API web
Una chiamata a un’API web è una richiesta e una risposta. Il client invia una richiesta HTTP a una URL (un endpoint) usando un metodo che segnala la sua intenzione, e il server restituisce un codice di stato e di solito dei dati. I metodi più comuni:
- GET — leggere dati (« dammi l’utente 42 »).
- POST — creare qualcosa di nuovo.
- PUT / PATCH — aggiornare qualcosa.
- DELETE — eliminare qualcosa.
Una semplice richiesta per leggere un utente potrebbe assomigliare a questa, con il server che risponde in JSON:
GET /users/42 HTTP/1.1
Host: api.example.com
-- response --
200 OK
{ "id": 42, "name": "Ada", "active": true }Il 200 è un codice di stato che significa successo; 404 significa non trovato, 401 non autenticato, 500 un errore del server. Il corpo è JSON — il formato leggero e leggibile dall’uomo che la maggior parte delle API web usa per scambiare dati strutturati.
Autenticazione e chiavi
Molte API richiedono che tu ti identifichi con una chiave API o un token, inviato in un header della richiesta. Questo permette al fornitore di controllare chi usa il servizio, applicare limiti di frequenza e fatturare l’uso. Tieni le chiavi segrete — una chiave trapelata è come una password trapelata.
Perché le API contano
Le API sono ciò che permette di comporre il software invece di ricostruirlo. Un negozio può incassare pagamenti senza scrivere una banca; un’app può mostrare una mappa senza disegnare il mondo; i servizi di una stessa azienda si parlano tramite API interne. Trasformano le capacità altrui in mattoni che chiami in poche righe — ed è questo, in sostanza, il modo in cui si costruisce il software moderno.
I limiti onesti
Un’API è una dipendenza. Se il fornitore la modifica, ti limita la frequenza, alza i prezzi o chiude, il tuo software ne risente — per questo le buone API sono versionate e documentate, e per questo gestisci errori e timeout invece di dare per scontato che ogni chiamata riesca. Un’API nasconde la complessità; non la elimina.
In sintesi
Un’API è un contratto che permette a un programma di usare le capacità di un altro tramite un insieme definito di richieste e risposte, senza toccarne i meccanismi interni. Le API web/REST su HTTP con JSON sono il tipo che incontrerai più spesso, ma l’idea — un’interfaccia pubblicata, separata dall’implementazione sottostante — attraversa librerie, sistemi operativi e ogni programma ben strutturato. Impara a leggere la documentazione di un’API e potrai collegare quasi qualsiasi cosa a qualsiasi altra.
Nuovo a un linguaggio per costruire o chiamare API? Sfoglia il nostro indice delle guide per spiegazioni di programmazione chiare e originali.