Che cos'è un'API (interfaccia di programmazione)?

Un’API è un insieme di regole che permette a un’applicazione di richiedere dati e funzionalità a un’altra senza conoscerne il codice interno. La famosa analogia del ristorante – si ordina da un menu, la cucina resta invisibile – si merita la sua unica frase e niente di più, perché la cosa reale è più istruttiva della metafora: un’API è un contratto, e i contratti sono precisi.

Punti chiave

Anatomia di una richiesta e di una risposta di API HTTP

Nessuna spiegazione ben posizionata ne mostra una, quindi ecco una chiamata API intera – richiesta e risposta, nulla di nascosto:

POST /classes/Todo HTTP/1.1              ← metodo + endpoint
Host: api.example-backend.com
X-Api-Key: app-7f2c…                     ← identifica l'app che chiama
Authorization: Bearer eyJhbGci…          ← autentica l'utente
Content-Type: application/json

{ "title": "Ship the release", "done": false }

HTTP/1.1 201 Created                     ← stato: ha funzionato, risorsa creata
Location: /classes/Todo/xKd91m
Content-Type: application/json

{ "objectId": "xKd91m", "createdAt": "2026-07-24T10:30:00Z" }

La stessa chiamata attraverso un SDK – che non è altro che questo HTTP, avvolto nell’idioma del linguaggio usato:

// JavaScript / Node.js — Back4app JS SDK
// One API call: create a record via the auto-generated REST API
const todo = new Parse.Object('Todo');
todo.set('title', 'Ship the release');
todo.set('done', false);
await todo.save();
// Under the hood: POST /classes/Todo with a JSON body → 201 Created
console.log('Created with id', todo.id);

// Flutter / Dart — Back4app Flutter SDK
// One API call: create a record via the auto-generated REST API
final todo = ParseObject('Todo')
  ..set('title', 'Ship the release')
  ..set('done', false);
await todo.save();
// Under the hood: POST /classes/Todo with a JSON body → 201 Created
print('Created with id ${todo.objectId}');

// iOS / Swift — Back4app Swift SDK
// One API call: create a record via the auto-generated REST API
var todo = Todo()
todo.title = "Ship the release"
todo.done = false
todo.save { result in
    // Under the hood: POST /classes/Todo with a JSON body → 201 Created
    if case .success(let saved) = result { print("Created with id \(saved.id ?? "")") }
}

// Android / Kotlin — Back4app Android SDK
// One API call: create a record via the auto-generated REST API
val todo = ParseObject("Todo")
todo.put("title", "Ship the release")
todo.put("done", false)
todo.saveInBackground { e ->
    // Under the hood: POST /classes/Todo with a JSON body → 201 Created
    if (e == null) println("Created with id ${todo.objectId}")
}

Come funziona una chiamata API

Tre proprietà di questo ciclo spiegano perché le API fanno girare lo stack moderno. Astrazione: al chiamante serve il contratto, mai l’implementazione – il provider può riscrivere tutto dietro l’interfaccia senza rompere un solo client. Confine: validazione e permessi vivono all’interfaccia, ed è per questo che i client parlano alle API e mai direttamente al database – un’API non è un database; è il custode che gli sta davanti. Composizione: poiché ogni capacità è invocabile, le applicazioni si assemblano a partire da servizi – l’autenticazione qui, i pagamenti là, le mappe da un terzo – e sempre più gli agenti IA usano lo stesso substrato: il tool calling è chiamare API con un modello che decide le richieste.

Il contratto: che cosa promette davvero un’API

Le pagine che definiscono un’API “un contratto” raramente ne mostrano uno. Oggi il contratto è un documento leggibile dalle macchine – l’OpenAPI Specification è lo standard per le API HTTP – che elenca ogni endpoint, parametro, schema e codice di stato. Da quel solo file gli strumenti generano documentazione di riferimento, librerie client, stub di server, server mock e test di contratto.

L’inquadramento contrattuale ha denti grazie al versionamento. Aggiungere un campo alla risposta non rompe nessuno; rinominarlo o rimuoverlo rompe in silenzio ogni consumatore – per questo le API mature distinguono le modifiche additive da quelle che rompono, versionano la propria superficie (/v1/, oppure tramite header) e pubblicano finestre di deprecazione. Un’API senza una politica di cambiamento è un contratto senza clausole: tecnicamente una promessa, in pratica una sorpresa.

I tipi di API

In forma di query, perché “tipi di API” è una ricerca a sé: due tassonomie, non una.

Per pubblico:

Per stile: REST (risorse a degli URL, metodi HTTP), GraphQL (query modellate dal client su un solo endpoint), gRPC (binario, contract-first, da servizio a servizio), SOAP (buste XML, standard enterprise/legacy) e le API WebSocket (bidirezionali, persistenti) – confrontate nella tabella seguente.

E un paragrafo che le spiegazioni sul web saltano: non ogni API è un’API web. La libreria standard di un linguaggio, le chiamate di sistema POSIX e le interfacce fetch e di geolocalizzazione integrate nel browser sono tutte API – contratti fra programmi – che non attraversano mai una rete. La variante web ha soltanto messo il contratto dietro un URL.

REST vs. GraphQL vs. gRPC vs. SOAP vs. WebSocket

Casi d’uso tipici

• Backend mobile e web – i dati di ogni schermata arrivano attraverso un’API; il frontend non tocca mai il database.
• Integrazione di terze parti – pagamenti, identità, messaggistica, mappe: capacità affittate tramite contratti invece di essere ricostruite.
• Comunicazione fra microservizi – le API interne come le cuciture che permettono ai servizi di essere rilasciati e scalati in modo indipendente.
• Automazione e scripting – tutto ciò che ha un’API si può orchestrare: pipeline di CI, infrastruttura, flussi di contenuti.
• Agenti IA e tool calling – i modelli agiscono invocando API; un contratto bene documentato è ormai consumato due volte dalle macchine, dagli SDK e dagli agenti.

Quale stile di API scegliere? Matrice decisionale

Limiti e trade-off

• Un contratto lega anche il provider. Ogni campo pubblicato diventa qualcosa da cui qualcuno dipende; l’evoluzione passa dalla disciplina di versionamento, non da modifiche silenziose.
• Le API di rete ereditano la rete. Latenza, guasti parziali e retry fanno parte della semantica di ogni chiamata remota – le chiamate di funzione locali non hanno mai avuto bisogno di politiche di timeout.
• L’astrazione nasconde il costo. Una chiamata dall’aspetto innocente può diramarsi in lavoro costoso; i consumatori vedono il menu, non il conto della cucina – ed è a questo che servono i rate limit e le quote.
• La superficie di sicurezza cresce con la superficie esposta. Ogni endpoint è una porta; le chiavi identificano ma non autorizzano, quindi un’autenticazione vera (token in stile OAuth 2.0, permessi per singolo utente) e la validazione degli input sono il minimo indispensabile.
• Le forme fisse non calzano a tutti i consumatori. I trade-off di overfetching e underfetching nel design degli endpoint sono un argomento a sé – si veda la voce gemella.

Le API su Back4app

Back4app è una piattaforma open-source di Backend as a Service (BaaS) che combina database gestito, API REST e GraphQL generate automaticamente, autenticazione, archiviazione di file e funzioni serverless con Cloud Code. La mossa che definisce tutto è che l’API è generata, non costruita: si definisce un modello di dati e la piattaforma lo espone subito come endpoint REST e schema GraphQL – la chiamata sezionata qui sopra è il vero formato che Back4app scambia sulla rete – con chiavi, token utente e permessi a livello di classe che fanno rispettare il contratto al confine. Gli SDK consumano quell’API in modo idiomatico da ogni piattaforma principale, e le operazioni su misura diventano funzioni Cloud Code: nuovi endpoint in un file, la stessa disciplina di contratto, nessun server da far girare.